# How to Install Cactus Needle: Complete Setup Guide for Inference and Training

> Install Cactus Needle easily with pip for efficient inference and training. Add extras for LoRA fine-tuning and GPU/Metal acceleration. Get started today!

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

---

**Install Cactus Needle with `pip install cactus-needle` for the lightweight 14 MB runtime, or add extras like `[train]` for LoRA fine-tuning and `[gpu]`/`[metal]` for hardware acceleration.**

Cactus Needle is a compact Python package for tool-calling, inference, and LoRA fine-tuning of foundation models. Whether you need a minimal runtime or a full training pipeline on GPU or Apple Silicon, the installation process is straightforward through pip with flexible optional dependencies defined in the project's [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml).

## Core Installation

The base runtime provides everything needed for inference and tool execution:

```sh
pip install cactus-needle

```

This installs:
- The **Needle inference engine** (model weights download lazily from Hugging Face)
- Core dependencies including `huggingface_hub` for model retrieval as specified in [[`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L8-L10)

Weights are not bundled with the package—your first inference call fetches only the required model files from Hugging Face.

## Optional Installation Extras

Cactus Needle uses **extras** to keep the base install minimal while enabling advanced functionality through modular dependencies.

### `[train]` — Training and Fine-Tuning

Installs the stack for LoRA fine-tuning, data generation, and model building:

```sh
pip install "cactus-needle[train]"

```

Adds: **NumPy**, **JAX**, **Flax**, **Optax**, and **SentencePiece** as declared in [`pyproject.toml#L13-L20`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L13-L20)

### `[gpu]` — CUDA Acceleration

Enables GPU-accelerated training with JAX compiled for CUDA 12:

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

```

Dependencies defined in [`pyproject.toml#L21-L22`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L21-L22)

### `[metal]` — Apple Silicon Support

Supplies JAX-Metal builds for GPU acceleration on macOS:

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

```

Configuration in [`pyproject.toml#L22-L26`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L22-L26)

### `[test]` — Development Dependencies

Installs testing utilities used by the repository's test suite:

```sh
pip install "cactus-needle[test]"

```

Includes `pytest` and `pydantic` per [`pyproject.toml#L27-L28`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L27-L28)

### Combining Extras

Install multiple extras together with comma separation:

```sh
pip install "cactus-needle[train,gpu]"

```

## Verify Your Installation

Confirm the package is properly installed and check its version:

```python
import needle

print(needle.__version__)  # → 2.0.8 (as defined in pyproject.toml)

```

The version is declared in [`pyproject.toml#L2-L4`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml#L2-L4).

## Quick Start Examples

### Basic Inference (No Training)

```sh
pip install cactus-needle

```

```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 it like in Lagos right now?")["results"])

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

```

Example from the project README at [`README.md#L44-L55`](https://github.com/cactus-compute/needle/blob/main/README.md#L44-L55).

### Fine-Tune with LoRA

```sh
pip install "cactus-needle[train,gpu]"

```

```python
import needle

# Requires data file `data.jsonl`

needle.finetune("data.jsonl", epochs=10, lora_rank=16, lora_alpha=32)

```

### Build and Deploy a Tuned Model

```sh
needle build checkpoints/needle2.pkl \
    --lora checkpoints/needle_lora.pkl \
    --out my_needle.cact

```

```python
import needle

agent = needle.Needle(weights="my_needle.cact", tools=[get_weather])
print(agent.run("What's the weather in Paris?"))

```

## Disable Telemetry

Cactus Compute sends anonymous usage telemetry (function name, package version, OS). Disable it with either environment variable:

```sh
export NEEDLE_TELEMETRY=0

# or

export DO_NOT_TRACK=1

```

Configuration documented in [`README.md#L55-L56`](https://github.com/cactus-compute/needle/blob/main/README.md#L55-L56).

## Key Source Files

Understanding the package structure helps with troubleshooting and extension:

| File | Purpose |
|------|---------|
| [[`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml)](https://github.com/cactus-compute/needle/blob/main/pyproject.toml) | Package metadata, dependencies, and extras configuration |
| [[`README.md`](https://github.com/cactus-compute/needle/blob/main/README.md)](https://github.com/cactus-compute/needle/blob/main/README.md) | User documentation and quickstart examples |
| [[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) | Public API: `Needle`, `tool`, `extract`, etc. |
| [[`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) | Command-line entry point for `needle` commands |
| [`needle/model/`](https://github.com/cactus-compute/needle/tree/main/needle/model) | Core architecture, quantization, and inference logic |
| [`needle/environments/`](https://github.com/cactus-compute/needle/tree/main/needle/environments) | Pre-built tool surfaces (smart home, media player, etc.) |

## Summary

- **Minimal install**: `pip install cactus-needle` — 14 MB runtime with lazy model downloads
- **Training stack**: Add `[train]` for JAX-based LoRA fine-tuning
- **Hardware acceleration**: Use `[gpu]` for CUDA 12 or `[metal]` for Apple Silicon
- **Version verification**: Import and check `needle.__version__` confirms successful installation
- **Privacy control**: Set `NEEDLE_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable analytics

## Frequently Asked Questions

### What Python version is required for Cactus Needle?

The package requires Python 3.9 or higher as specified in [`pyproject.toml`](https://github.com/cactus-compute/needle/blob/main/pyproject.toml). Ensure your environment runs a compatible version before installation.

### Can I install Cactus Needle without GPU support?

Yes. The base `pip install cactus-needle` includes no GPU dependencies. GPU support is entirely optional through the `[gpu]` and `[metal]` extras, making the package suitable for CPU-only deployments.

### How large is the Cactus Needle download?

The Python package itself is approximately 14 MB. Model weights are downloaded separately on first use from Hugging Face, so initial installation remains lightweight regardless of which model you intend to use.

### What if my LoRA fine-tuning fails to import JAX?

Ensure you installed the appropriate extra for your hardware: `[train]` alone provides CPU JAX, `[train,gpu]` enables CUDA acceleration, and `[train,metal]` is required for Apple Silicon. The error typically indicates a missing hardware-specific JAX build.