# System Requirements for Running Needle 2: Minimal Hardware and Software Specs

> Discover Needle 2 system requirements. Run inference on any CPU with Python 3.9+, 28MB RAM, and a 14MB download. Optional GPU acceleration for CUDA and Apple Silicon.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: getting-started
- Published: 2026-09-08

---

**Needle 2 requires only Python 3.9+, approximately 28 MiB of RAM, and a 14 MiB binary download to run inference on any modern CPU, with optional GPU acceleration available for CUDA and Apple Silicon devices.**

Needle 2 is a tiny, self-contained 45-million-parameter language model developed by Cactus Compute that delivers efficient inference without external runtimes. This guide explains the **system requirements for running Needle 2** on your local machine, covering hardware specifications, Python environment constraints, and optional acceleration methods defined in the cactus-compute/needle repository.

## Minimum Hardware Specifications

Needle 2 is designed to run on virtually any modern computer with minimal resource overhead. The base inference engine requires no specialized hardware to execute.

### Memory and Storage Requirements

The complete runtime footprint for Needle 2 is exceptionally small compared to contemporary language models:

- **RAM**: Approximately **28 MiB** of RAM for a full inference session
- **Binary Size**: The engine file is approximately **14 MiB** and downloads automatically from Hugging Face on first use
- **Caching**: After the initial download, the inference engine is cached locally, enabling instant subsequent starts without repeated network requests

### CPU Requirements

As implemented in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py), Needle 2 runs entirely on the CPU with no external runtime dependencies. The **45M-parameter model** executes efficiently on any modern processor architecture, making it suitable for edge devices and resource-constrained environments where GPU acceleration is unavailable.

## Software Prerequisites

The primary constraint for running Needle 2 is the Python environment version and basic operating system compatibility.

### Python Version Constraints

According to the [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) configuration in the cactus-compute/needle repository, the package requires **Python 3.9 or newer**. The package is published on PyPI as `cactus-needle` and installs via standard pip commands.

### Operating System Support

Needle 2 works on any platform supported by Python, including:

- Linux distributions
- macOS (Intel and Apple Silicon)
- Windows

The pure-Python implementation ensures cross-platform compatibility without platform-specific binaries.

## Installation and Dependencies

The base installation pulls in a minimal set of dependencies defined in [`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt), including `pydantic` and `numpy`. All dependencies install automatically via pip.

### Base Package Installation

Install the core package using pip:

```bash
pip install cactus-needle

```

This command automatically downloads the 14 MiB engine file from Hugging Face and installs the pure-Python dependency stack. The [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) file contains the core `Needle` class, `tool` decorator, and `extract` helper used for inference.

### Dependency Structure

The [`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt) specifies a small set of pure-Python packages:

- **pydantic**: For structured data validation and extraction
- **numpy**: For numerical operations
- **jax**: Installed automatically when using optional training features

## Optional GPU Acceleration

While Needle 2 runs efficiently on CPU, the repository supports optional GPU acceleration for faster training and inference through extras packages.

### CUDA Support

For NVIDIA GPUs, install the GPU extras:

```bash
pip install "cactus-needle[gpu]"

```

This configuration enables CUDA-accelerated operations as documented in [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md).

### Apple Silicon Support

For M-series Macs, use the Metal extras:

```bash
pip install "cactus-needle[metal]"

```

This leverages Apple's Metal Performance Shaders for acceleration on M1, M2, and M3 processors.

### Fine-Tuning Requirements

The optional training workflow documented in [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md) supports LoRA (Low-Rank Adaptation) fine-tuning using the GPU or Metal backends. Fine-tuning requires the same base memory specifications but benefits significantly from acceleration hardware for training speed.

## Running Needle 2: Implementation Examples

The following examples demonstrate practical usage within the specified system requirements.

### Tool-Calling Inference

This example uses the default CPU-based engine installed via `pip install cactus-needle`:

```python
import needle

@needle.tool
def get_weather(city: str):
    """Get the current weather for a city."""
    return {"city": city, "temp_c": 27, "sky": "clear"}

agent = needle.Needle(tools=[get_weather])
print(agent.run("What's the weather like in Lagos?")["results"])

# → [{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]

```

### Structured Data Extraction

Using Pydantic models for type-safe extraction as defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py):

```python
from pydantic import BaseModel
import needle

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

text = "Invoice from Acme Corp, $1,200.00, due 2026-09-01"
invoice = needle.extract(text, Invoice)
print(invoice.vendor, invoice.total)   # → Acme Corp 1200.0

```

### GPU-Accelerated Fine-Tuning

For systems with optional GPU support:

```bash
pip install "cactus-needle[gpu]"   # or [metal] on Apple Silicon

needle finetune data.jsonl --epochs 10   # LoRA training

needle build checkpoints/needle2.pkl \
    --lora checkpoints/needle_lora.pkl \
    --out my_needle.cact

```

Load the fine-tuned model:

```python
import needle
agent = needle.Needle(weights="my_needle.cact", tools=[...])
agent.run("...")   # using the tuned model

```

## Summary

- **Needle 2 system requirements** include Python 3.9+, 28 MiB RAM, and 14 MiB storage, making it one of the most lightweight language model deployments available.
- The **cactus-needle** package installs automatically via pip and caches the inference engine after the first download.
- CPU-only operation requires no external runtimes or GPU hardware, as implemented in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py).
- Optional acceleration is available through `pip install "cactus-needle[gpu]"` for CUDA or `[metal]` for Apple Silicon.
- The complete dependency stack is defined in [`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt) and installs automatically with the base package.

## Frequently Asked Questions

### What is the minimum RAM needed to run Needle 2?

Needle 2 requires approximately **28 MiB of RAM** for a full inference session. This minimal footprint allows the model to run on embedded devices, older hardware, or alongside memory-intensive applications without resource contention.

### Does Needle 2 require a GPU to function?

No. Needle 2 runs entirely on CPU using the pure-Python implementation in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). GPU acceleration is optional and available only for improving training speed or inference latency when using the `[gpu]` or `[metal]` extras packages.

### Which Python versions are compatible with Needle 2?

The [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) specifies **Python 3.9 or newer**. The package is tested and distributed on PyPI as `cactus-needle`, with automatic dependency resolution for all supported Python versions.

### How large is the Needle 2 model download?

The engine file is approximately **14 MiB** and downloads automatically from Hugging Face when you first import the package. After the initial download, the binary is cached locally, eliminating network overhead for subsequent sessions.