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

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, 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 and documented in the quickstart section of 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, 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 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 and the GPU extras section of README.md, you can install platform-specific variants:

NVIDIA CUDA Support

pip install "cactus-needle[gpu]"

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

Apple Silicon Optimization

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:

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:

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:

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:

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.
• 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. 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 and the quickstart documentation. This version constraint ensures compatibility with the type hinting and async features utilized in 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. The complete environment typically occupies under 50 MiB, making Needle 2 one of the most compact deployable language model solutions available.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}