# How to Install the cactus-needle Python Package: A Complete Guide

> Easily install the cactus-needle Python package using pip. Learn commands for CPU, NVIDIA CUDA 12 GPU, and Apple Silicon Metal installations. Get started today.

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

---

**Install cactus-needle with `pip install cactus-needle` for CPU, `pip install "cactus-needle[gpu]"` for NVIDIA CUDA 12, or `pip install "cactus-needle[metal]"` for Apple Silicon.**

The **cactus-needle** package provides a self-contained 14 MB inference engine for the Needle 2 model, including LoRA fine-tuning utilities and a command-line interface. This guide covers installation from PyPI, verification steps, and backend-specific configurations based on the source code in the `cactus-compute/needle` repository.

## Prerequisites

Before installing cactus-needle, ensure your environment meets these requirements:

- **Python ≥ 3.9** — specified in the `[project.requires-python]` field of [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L5】
- A working **pip** environment (virtual environment recommended)

## Basic Installation

The core package installs the inference engine with all required runtime dependencies. According to the **dependencies** section in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L8-L16】, this pulls in `huggingface_hub`, `numpy`, `jax`, `jaxlib`, `flax`, `optax`, and `sentencepiece`.

```bash
pip install cactus-needle

```

This gives you:
- The `Needle` class for tool-calling and extraction
- The `@needle.tool` decorator for defining callable tools
- The `needle` CLI entry point

## Optional GPU and Apple Silicon Acceleration

The package defines two **extra dependency groups** for hardware acceleration, declared in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L19-L20】:

| Extra | Hardware | Command |
|-------|----------|---------|
| **gpu** | NVIDIA GPUs (CUDA 12) | `pip install "cactus-needle[gpu]"` |
| **metal** | Apple Silicon (MPS) | `pip install "cactus-needle[metal]"` |

### NVIDIA GPU Installation

The `gpu` extra installs `jax[cuda12]` for CUDA 12 acceleration:

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

```

### Apple Silicon (Metal) Installation

The `metal` extra installs `jax-metal` with pinned compatible versions of `jax`, `jaxlib`, `flax`, and `optax`:

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

```

## Verifying Your Installation

After installation, verify the package and CLI are correctly registered. The `needle` console script is defined under `[tool.setuptools.scripts]` in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L23-L25】.

Check the installed version:

```bash
python -c "import needle, sys; print('needle version', needle.__version__)"

```

Verify the CLI entry point:

```bash
needle --help

```

## Quick Start After Installation

The **public API** is exposed through [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), which includes the `Needle` class and `tool` decorator used in quick-start examples【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/__init__.py】.

### Example: Tool-Calling in Python

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

# Create agent with your tools

agent = needle.Needle(tools=[get_weather])

# The model automatically calls the tool when needed

response = agent.run("What's it like in Lagos right now?")
print(response["results"])

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

```

### Example: Using the CLI

The CLI implementation resides in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/cli.py】:

```bash

# Run a query without writing Python code

needle "Summarize the benefits of tool calling in Needle"

```

### Example: LoRA Fine-Tuning

Fine-tuning requires JAX; use the `[gpu]` or `[metal]` extras for acceleration:

```bash

# Prepare a JSONL dataset per doc/finetuning.md, then:

needle finetune my_data.jsonl --epochs 5

```

## Key Files and Their Roles

| File | Purpose |
|------|---------|
| [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml】 | Package metadata, dependencies, and `needle` console script |
| [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/__init__.py】 | Public API: `Needle`, `tool`, `extract` |
| [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/cli.py】 | CLI implementation |
| `needle/model/` | Core inference engine (tokenizer, run loop, quantization) |
| [`doc/finetuning.md`](https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md) | LoRA fine-tuning instructions |

## Summary

- **cactus-needle** is distributed on PyPI and requires Python ≥ 3.9
- **Base install**: `pip install cactus-needle` — includes JAX CPU backend
- **GPU extras**: Use `[gpu]` for NVIDIA CUDA 12 or `[metal]` for Apple Silicon
- **Verify** with `python -c "import needle; print(needle.__version__)"` and `needle --help`
- The package exposes tools for **inference**, **tool-calling**, **extraction**, and **fine-tuning** with minimal dependencies

## Frequently Asked Questions

### What Python versions are compatible with cactus-needle?

Python 3.9 and later. This requirement is explicitly declared in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) under `[project.requires-python]`【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L5】.

### Do I need a GPU to use cactus-needle?

No. The base installation includes JAX with CPU support. GPU acceleration is optional via the `[gpu]` or `[metal]` extras for improved fine-tuning and inference performance.

### How do I check if my installation detected the GPU?

After installing with `[gpu]` or `[metal]`, run:

```python
import jax
print(jax.devices())

```

This should list your available accelerators. If only CPUs appear, revisit your JAX installation for your specific platform.

### Where is the CLI entry point defined?

The `needle` command is registered as a console script in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) under `[tool.setuptools.scripts]`【/cache/repos/github.com/cactus-compute/needle/main/pyproject.toml#L23-L25】, which points to the implementation in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/cactus-compute/needle/main/needle/cli.py】.