# System Requirements for Running Needle 2: Minimal Setup Guide

> Discover Needle 2 system requirements: Python 3.9+, 28 MiB RAM, and a 14 MiB binary. Runs on modern CPUs, with optional GPU acceleration for CUDA and Apple Silicon.

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

---

**Needle 2 requires only Python 3.9+, approximately 28 MiB of RAM, and a single 14 MiB binary file to run 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 published by `cactus-compute/needle` on PyPI as `cactus-needle`. Understanding the system requirements for running Needle 2 ensures you can deploy this lightweight engine for tool-calling and structured extraction on anything from embedded devices to cloud servers without managing complex dependencies or external runtimes.

## Minimum Hardware and Software Specifications

### Python Version and Operating System

Needle 2 targets **Python 3.9 or newer**, as defined in the project's [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) build configuration. The package runs on any platform supported by Python, including Linux, macOS, and Windows. Because the inference engine is self-contained within the `cactus-needle` package, no additional system libraries or external runtimes are required.

### Memory and Storage Footprint

The model is optimized for minimal resource consumption:

- **RAM**: Approximately **28 MiB** for a full inference session
- **Binary Size**: A single **14 MiB** engine file downloaded automatically from Hugging Face on first use
- **Caching**: The engine is cached locally after initial download, making subsequent runs instant

According to the [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md) in the `cactus-compute/needle` repository, these specifications make Needle 2 suitable for edge devices and resource-constrained environments where larger frameworks like PyTorch or TensorFlow would be impractical.

### CPU Requirements

Needle 2 runs entirely on the CPU using optimized inference code. As implemented in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py), the engine requires no GPU for standard inference tasks. The `Needle` class in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) handles all computation through pure-Python orchestration with minimal overhead, making it compatible with any modern processor architecture.

## Optional GPU and Metal Acceleration

While CPU inference is sufficient for most use cases, you can install optional extras for faster training and large-scale inference workloads.

### CUDA Support for NVIDIA GPUs

For CUDA-enabled systems, install the GPU variant to accelerate training and batch inference:

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

```

This extra dependency enables CUDA acceleration during fine-tuning workflows defined in [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md), though the base inference engine remains CPU-only unless specifically configured for GPU execution during training.

### Apple Silicon Optimization

On Apple M1, M2, or M3 devices, use the Metal backend for optimized performance:

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

```

This configuration leverages the Metal Performance Shaders framework for LoRA fine-tuning, allowing you to train custom adapters directly on Mac hardware without external cloud resources.

## Installation and Dependencies

The base package installs via `pip` with a minimal dependency tree defined in [`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt):

```bash
pip install cactus-needle

```

The package automatically pulls in pure-Python dependencies including:

- **pydantic**: For structured data validation in `needle.extract()`
- **numpy**: For numerical operations in the inference engine
- **jax**: Optional training dependency for gradient computation

All dependencies are installed automatically, and the 14 MiB binary engine downloads on first import, requiring no manual configuration.

## Verifying Your Setup with Code Examples

Test your installation with these practical examples that demonstrate Needle 2's core capabilities within the minimal resource footprint.

### Tool-Calling with 28 MiB RAM

This example uses the `needle.tool` decorator and `Needle` class from [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) to execute functions:

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

Use `needle.extract()` with Pydantic models for type-safe data parsing:

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

After installing GPU or Metal extras, run LoRA fine-tuning:

```bash

# Install acceleration first

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

# Fine-tune and build custom weights

needle finetune data.jsonl --epochs 10
needle build checkpoints/needle2.pkl \
    --lora checkpoints/needle_lora.pkl \
    --out my_needle.cact

```

Load custom weights in Python:

```python
import needle
agent = needle.Needle(weights="my_needle.cact", tools=[...])
agent.run("...")

```

## Behind the Scenes: Key Implementation Files

Understanding the architecture helps clarify why the system requirements remain minimal:

- **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)**: Contains the core `Needle` class, `tool` decorator, and `extract()` helper functions that orchestrate the 45M-parameter model
- **[`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py)**: Implements the lightweight inference engine entry point that executes within the 28 MiB memory constraint
- **[`requirements.txt`](https://github.com/cactus-compute/needle/blob/main/requirements.txt)**: Lists minimal pure-Python dependencies ensuring broad compatibility
- **[`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)**: Defines Python 3.9+ version constraints and package metadata for `cactus-needle`
- **[`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md)**: Documents system facts handling and API configuration
- **[`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md)**: Provides guidance for optional GPU/Metal acceleration during training

## Summary

- **Python 3.9 or newer** is required to run Needle 2, available on Linux, macOS, and Windows
- **28 MiB of RAM** and **14 MiB of storage** are sufficient for full inference sessions
- **CPU-only operation** is supported out of the box with no external runtime dependencies
- **Optional GPU extras** (`[gpu]` for CUDA, `[metal]` for Apple Silicon) accelerate training but are not required for inference
- The `cactus-needle` package from `cactus-compute/needle` installs all dependencies automatically via pip

## Frequently Asked Questions

### How much RAM is actually required to run Needle 2?

Needle 2 requires approximately **28 MiB of RAM** for a complete inference session. The 14 MiB binary engine loads into memory while maintaining a minimal footprint suitable for containerized deployments and edge devices. According to the `cactus-compute/needle` README, this makes it one of the smallest functional language model implementations available via PyPI.

### Can I run Needle 2 without a GPU?

Yes. Needle 2 is designed to run entirely on CPU using the self-contained engine in [`needle/model/run.py`](https://github.com/cactus-compute/needle/blob/main/needle/model/run.py). The GPU and Metal extras are only necessary if you plan to perform LoRA fine-tuning or require accelerated inference for high-throughput applications. Standard tool-calling and structured extraction work efficiently on any modern CPU.

### What Python version do I need to install?

You need **Python 3.9 or newer**, as specified in the project's [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml). The package is published on PyPI as `cactus-needle` and supports all platforms where Python runs, including ARM64 and x86-64 architectures. The [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) module uses modern Python typing features that require 3.9+.

### How large is the model file that gets downloaded?

The engine file is approximately **14 MiB** and downloads automatically from Hugging Face on first use. The file is cached locally after initial download, meaning subsequent runs start instantly without additional network requests or storage overhead. This single binary contains the full 45-million-parameter model weights optimized for the inference runtime.