# How to Install the Needle 2 Model: Complete Setup Guide

> Install Needle 2 easily with pip install cactus-needle. Get the 45M parameter weights from Hugging Face automatically when you start using Needle.

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

---

**Install Needle 2 by running `pip install cactus-needle`; the 45M-parameter weights auto-download from Hugging Face when you first instantiate `needle.Needle()`.**

The `cactus-compute/needle` repository ships Needle 2 as a compact Python distribution that bundles the inference engine and a pre-quantized checkpoint into a single workflow. With a standard installation size of approximately 14 MB and no manual weight management required, you can deploy this tool-calling model on CPU, CUDA, or Apple Silicon in minutes.

## Installing the Core Package

The base installation pulls in the runtime and all required dependencies via a single command. According to the source code in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) [[source](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L2-L16)], the package declares dependencies such as `jax`, `flax`, and `numpy` automatically.

```bash
pip install cactus-needle

```

After installation, the `needle` CLI becomes available, and the Python API in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) exposes the core `Needle` class for agent construction and weight loading.

## Adding Hardware Acceleration (Optional)

For platforms with GPU support, install the appropriate extras to enable hardware acceleration. The optional dependency groups are defined in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) [[source](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L18-L21)].

- **NVIDIA GPUs**: Install CUDA support using the `[gpu]` extra.

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

```

- **Apple Silicon**: Enable Metal Performance Shaders with the `[metal]` extra.

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

```

## Downloading the Model Weights

Needle 2 eliminates manual weight management. The first time you instantiate `needle.Needle` or run a CLI command that requires inference, the engine automatically downloads the 45M-parameter checkpoint from **Hugging Face** ([Cactus-Compute/needle2](https://huggingface.co/Cactus-Compute/needle2)) and caches it locally.

To trigger the download explicitly or verify the cache, use the CLI command defined in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py):

```bash
needle build

```

The downloaded artifact is a single `.cact` binary file. As noted in the [`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md) [[source](https://github.com/cactus-compute/needle/blob/main/README.md#L9-L14)], the inference engine memory-maps this file directly, maintaining a constant RAM footprint of approximately 28 MB regardless of conversation length.

## Verifying the Installation

Create a minimal agent to confirm that the package and weights are functioning. The following example, adapted from [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) and the repository documentation, defines a simple tool and runs a structured query:

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

# Weights auto-download on first use if not cached

agent = needle.Needle(tools=[get_weather])
result = agent.run("What's the temperature in Tokyo?")
print(result["results"])

# Output: [{'city': 'Tokyo', 'temp_c': 27, 'sky': 'clear'}]

```

Successful execution confirms that the `cactus-needle` package, its dependencies, and the `.cact` weight file are correctly installed.

## Loading Custom Weights (Optional)

If you possess a fine-tuned checkpoint, supply the path directly to the `Needle` constructor instead of using the auto-cached base weights. This behavior is handled in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) via the `weights` parameter:

```python
agent = needle.Needle(weights="my_fine_tuned.cact", tools=[get_weather])
response = agent.run("Tell me about the sky in Berlin.")

```

## Summary

- **Install via PyPI**: Run `pip install cactus-needle` to install the core package (~14 MB) with all Python dependencies listed in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml).
- **Enable acceleration**: Add `[gpu]` for CUDA or `[metal]` for Apple Silicon extras during installation.
- **Auto-download weights**: The 45M-parameter checkpoint downloads automatically from Hugging Face on first use; manually trigger with `needle build`.
- **Zero-config caching**: Weights are stored as a single `.cact` file and memory-mapped for efficient 28 MB RAM usage.
- **Custom models**: Pass a local path to the `weights` parameter in `needle.Needle()` to load fine-tuned variants.

## Frequently Asked Questions

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

The Needle 2 checkpoint contains 45 million parameters and is distributed as a single `.cact` binary file. The Python package itself is approximately 14 MB, and the total installation footprint remains under 50 MB, making it suitable for edge devices and containerized deployments.

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

No. Needle 2 runs efficiently on CPU-only systems using the base `pip install cactus-needle` command. However, for improved inference speed on NVIDIA GPUs or Apple Silicon Macs, install the optional `[gpu]` or `[metal]` extras to enable hardware acceleration via JAX.

### Where are the model weights cached locally?

The weights are downloaded from Hugging Face ([Cactus-Compute/needle2](https://huggingface.co/Cactus-Compute/needle2)) and cached automatically the first time you instantiate `needle.Needle()` or execute `needle build`. The engine manages the cache location internally; you do not need to specify a directory unless loading a custom `.cact` file via the `weights` argument.

### Can I use Needle 2 with fine-tuned checkpoints?

Yes. While the library defaults to the pre-trained base weights, you can load custom fine-tuned models by providing a file path to the `weights` parameter when initializing the `Needle` class: `needle.Needle(weights="path/to/custom.cact", tools=[...])`. This allows you to deploy specialized agents without modifying the core package.