# Needle 2 Binary Size: A Lightweight 14 MB Engine Explained

> Discover the Needle 2 binary size at just 14 MB. This single core inference engine from Hugging Face downloads once and caches locally for fast, repeated use.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: deep-dive
- Published: 2026-08-19

---

**The Needle 2 binary size is 14 MB, delivered as a single core inference engine that downloads once from Hugging Face and caches locally for all subsequent runs.**

The `cactus-compute/needle` repository is built around a minimal footprint philosophy, and the Needle 2 binary size reflects that design. Weighing just 14 MB on disk, the engine runs a full inference session in approximately 28 MB of RAM. This compact profile is documented directly in the project's README and supporting source files.

## Where the 14 MB Size Is Documented

Two key files in the repository explicitly state the exact dimensions of the engine.

- **[`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md)** — The project's main documentation notes that Needle 2 ships as a "single **14 MB** binary" that handles core inference.
- **[`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt)** — This supplementary file repeats the specification, stating that "the inference engine is a **14 MB binary** fetched once from Hugging Face."

Both sources confirm that the Needle 2 binary size is fixed at 14 MB for standard distributions.

## How the Engine Is Fetched and Cached

The Python package handles acquisition automatically. When you instantiate the top-level `Needle` class exposed in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), the library checks for the engine in your local cache. If it is missing, the download logic inside [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py) retrieves the file from Hugging Face.

The default cache directory is `~/.cache/cactus-needle/`. After the first successful download, the binary remains on disk, eliminating redundant network requests across sessions. This behavior keeps the Needle 2 binary size constant at 14 MB regardless of how many times you run the model.

## How to Verify the Needle 2 Binary Size Locally

You can confirm the exact footprint of the downloaded engine using either the internal API or direct filesystem inspection.

### Check the Engine After First Use

Once you have initialized the model, the `_engine_path` attribute points to the cached binary on disk.

```python
import pathlib, needle

# Initialise the model – the engine is downloaded on first use

agent = needle.Needle()

# The engine is stored in the cache directory (default: ~/.cache/cactus-needle/)

engine_path = pathlib.Path(agent._engine_path)       # internal attribute used by Needle

size_mb = engine_path.stat().st_size / 1e6

print(f"Needle 2 engine file: {engine_path}")
print(f"Size: {size_mb:.2f} MB")

```

### Inspect the Cache Without Loading the Model

If you prefer not to instantiate the agent, you can locate the `*.bin` file directly in the cache folder.

```python
import pathlib, os

# Default cache location used by `cactus-needle`

cache_dir = pathlib.Path(os.getenv("XDG_CACHE_HOME", "~/.cache")).expanduser() / "cactus-needle"

# Find the first *.bin file (the engine binary)

engine_file = next(cache_dir.rglob("*.bin"))
print(f"Engine binary: {engine_file}")
print(f"Size: {engine_file.stat().st_size / 1e6:.2f} MB")

```

Both methods will report a Needle 2 binary size of roughly **14 MB**, assuming the engine has already been fetched.

## Key Source Files Behind the Binary

Several files in the `cactus-compute/needle` repository govern how the binary is distributed, documented, and accessed:

- **[`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md)** — Describes the 14 MB binary and overall architecture.
- **[`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt)** — Mentions the binary size and download behavior.
- **[`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py)** — Contains the logic that downloads and caches the engine binary from Hugging Face.
- **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)** — Exposes the top-level `Needle` class that triggers the engine download.
- **[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)** — Documents how the engine is retrieved and used by the Python API.

## Summary

- The Needle 2 binary size is a single **14 MB** file.
- It is fetched **once** from Hugging Face and stored in `~/.cache/cactus-needle/`.
- A complete inference session consumes approximately **28 MB** of RAM.
- Source documentation in [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md) and [`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt) explicitly confirms these figures.
- **[`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py)** and **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)** manage the download and caching lifecycle.

## Frequently Asked Questions

### What is the exact Needle 2 binary size?

The engine is a single file weighing exactly **14 MB**. This is stated in both [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md) and [`llms.txt`](https://github.com/cactus-compute/needle/blob/main/llms.txt) within the `cactus-compute/needle` repository.

### Where is the Needle 2 binary stored after download?

By default, the package caches the binary in `~/.cache/cactus-needle/`. You can override this path by setting the `XDG_CACHE_HOME` environment variable before running Needle.

### How much RAM does Needle 2 use during a session?

According to the repository documentation, a full session runs in about **28 MB** of RAM. This makes the engine suitable for edge devices and low-resource environments.

### Is the binary re-downloaded on every run?

No. The 14 MB engine is downloaded only on first use. Subsequent initializations load the binary directly from the local cache managed by [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py).