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

> Discover the minimal system requirements for Needle 2. Run inference on any modern CPU with Python 3.9+, 28 MiB RAM, and a 14 MiB binary. Optional GPU acceleration supported.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: system-requirements
- Published: 2026-08-14

---

**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 self-contained 45-million-parameter language model developed by cactus-compute/needle that operates efficiently on virtually any modern computer. Understanding the system requirements for running Needle 2 enables developers to deploy this lightweight inference engine across edge devices, laptops, and servers without managing complex dependencies or external runtimes. The base installation pulls a minimal binary from Hugging Face and executes entirely within Python, consuming negligible system resources.

## Core Hardware and Software Requirements

Needle 2 is engineered for extreme minimalism. According to the repository's [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md), the model operates within strict resource constraints that make it accessible for low-resource environments and embedded systems.

**CPU and Memory Specifications**

- **RAM**: Approximately 28 MiB for a full inference session
- **Binary Size**: Single 14 MiB engine file (cached automatically after first download from Hugging Face)
- **Processor**: Executes on any CPU architecture without requiring GPU acceleration or specialized instruction sets

**Python Environment Constraints**

The package is published on PyPI as `cactus-needle` with specific version requirements defined in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) and documented in the quickstart section of [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md):

- **Python Version**: 3.9 or newer required
- **Installation Command**: `pip install cactus-needle`
- **Operating Systems**: Linux, macOS, and Windows (any platform supporting Python)

### Storage and Dependency Footprint

The base package installs a minimal set of pure-Python dependencies automatically as specified in [`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt), including `pydantic`, `numpy`, and optional `jax` for training workflows. The complete installation typically remains under 50 MiB, with the inference engine in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py) requiring only the 14 MiB binary to execute.

## Optional GPU and Metal Acceleration

While Needle 2 runs inference efficiently on CPU using the default installation, the repository provides optional extras for hardware-accelerated training and inference. According to [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md) and the GPU extras section of [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md), you can install platform-specific variants:

**NVIDIA CUDA Support**

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

```

Enables GPU-accelerated computation for CUDA-capable NVIDIA hardware, significantly speeding up LoRA fine-tuning workflows.

**Apple Silicon Optimization**

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

```

Activates Metal Performance Shaders on Apple Silicon (M1/M2/M3) devices for optimized inference and training speed on macOS.

## Verifying Your Installation

After meeting the base system requirements, validate the setup by executing a simple tool-calling example using the `Needle` class defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py):

```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'}]

```

This demonstrates that the 14 MiB binary downloaded correctly and the environment satisfies all runtime dependencies.

### Structured Extraction Validation

Test Pydantic integration and JSON parsing capabilities to confirm complete environment functionality:

```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

```

### Fine-Tuning with Hardware Acceleration

If you installed the GPU or Metal extras, verify acceleration support during LoRA training as implemented in the CLI tools:

```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 custom weights to confirm the accelerated pipeline functions correctly:

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

```

## Summary

- **Minimal hardware footprint**: Needle 2 requires only Python 3.9+, 28 MiB RAM, and 14 MiB storage for the base inference engine defined in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py).
- **Self-contained execution**: No external runtimes or heavy frameworks required; all core functionality is packaged in the `cactus-needle` PyPI distribution.
- **Universal compatibility**: Functions on Linux, macOS, and Windows platforms where Python 3.9+ is available.
- **Hardware acceleration options**: Install `cactus-needle[gpu]` for CUDA support or `cactus-needle[metal]` for Apple Silicon to accelerate training and inference workflows.
- **Automatic caching**: The inference engine downloads once from Hugging Face and caches locally, enabling instant subsequent startups without repeated network overhead.

## 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 according to the model specifications documented in [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md). This minimal footprint makes it suitable for resource-constrained environments, edge computing deployments, and embedded systems where memory is limited.

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

No GPU is required for basic operation. Needle 2 runs efficiently on any CPU using the standard `pip install cactus-needle` command without external runtime dependencies. The optional GPU extras—`[gpu]` for CUDA-enabled NVIDIA hardware or `[metal]` for Apple Silicon—provide acceleration only for users requiring faster training or high-throughput inference scenarios.

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

The package requires Python 3.9 or newer as specified in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) and the quickstart documentation. This version constraint ensures compatibility with the type hinting and async features utilized in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) while maintaining broad platform support across modern Python installations.

### How much disk space does the Needle 2 installation consume?

The installation requires approximately 14 MiB for the binary engine file (downloaded automatically from Hugging Face and stored locally) plus minimal additional space for pure-Python dependencies listed in [`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt). The complete environment typically occupies under 50 MiB, making Needle 2 one of the most compact deployable language model solutions available.