Installation¶

NervaPack supports multiple installation methods. Choose the one that best fits your workflow.

Prerequisites¶

Before installing NervaPack, ensure you have:

Python 3.10+ (check with python --version)
Git (your project must be a git repository - run git init if needed)
LLM Provider (choose one):
- Ollama (local, privacy-first) — ollama.com
- Claude API (cloud) — console.anthropic.com
- OpenAI API (cloud) — platform.openai.com
- Claude Code/Cursor (MCP integration) — uses your existing session

Installation Methods¶

Option A: Homebrew (macOS/Linux — Recommended)¶

The easiest way to install on macOS or Linux:

brew tap ramdhavepreetam/nervapack
brew install nervapack

Verify installation:

nervapack --help

Option B: pipx (Isolated Install — Recommended)¶

Best for avoiding dependency conflicts:

# Install pipx if you don't have it
python -m pip install --user pipx
python -m pipx ensurepath

# Install NervaPack
pipx install nervapack

Verify installation:

nervapack --help

Option C: pip (Standard Python Install)¶

Install directly into your Python environment:

pip install nervapack

Verify installation:

nervapack --help

Optional Features¶

Install additional features as needed:

Exact Token Counting¶

pip install "nervapack[metrics]"

Adds tiktoken for precise token counting (vs character-based estimates).

Web Dashboard¶

pip install "nervapack[dashboard]"

Adds Streamlit and Plotly for the interactive web dashboard (nervapack serve).

MCP Server (Claude Code/Cursor Integration)¶

pip install "nervapack[mcp]"

Enables the MCP server for seamless integration with Claude Code and Cursor.

Cloud LLM Providers¶

# Claude API support
pip install "nervapack[claude]"

# OpenAI API support
pip install "nervapack[openai]"

# Both cloud providers
pip install "nervapack[cloud-llm]"

All Features¶

pip install "nervapack[all]"

Installs all optional features (metrics, dashboard, MCP, cloud LLMs).

Additional Language Support¶

NervaPack bundles Python, JavaScript, and TypeScript support. Add more tree-sitter languages:

# Individual languages
pip install "nervapack[go]"      # Go
pip install "nervapack[rust]"    # Rust
pip install "nervapack[java]"    # Java
pip install "nervapack[c]"       # C / C headers
pip install "nervapack[cpp]"     # C++
pip install "nervapack[ruby]"    # Ruby
pip install "nervapack[csharp]"  # C#

# All languages at once
pip install "nervapack[all-languages]"

IBM i / mainframe (RPG, CL, COBOL) — no extra needed¶

Since v0.7.0, NervaPack also indexes the IBM i / mainframe stack out of the box — no extra to install and no grammar to compile:

Language	Extensions
RPG	`.rpgle`, `.rpg`, `.sqlrpgle`
CL	`.clle`, `.clp`, `.cl`
COBOL	`.cbl`, `.cob`, `.cobol`, `.cpy`

These use a pure-Python extractor (not tree-sitter), so they work offline and in air-gapped environments with zero dependencies. CALL, COPY, and file declarations become typed, cross-file dependency edges. See IBM i Languages for details.

First-Time Setup¶

On first run, NervaPack will:

Download ChromaDB models (~1-2 minutes, one-time)
- ONNX runtime embedding models
- Stored in your system cache
Compile tree-sitter grammars (~30 seconds, one-time)
- Language parsers for AST extraction
- Cached for future use

First run

The initial setup is automatic. Subsequent runs are instant!

Upgrading¶

Homebrew¶

brew update
brew upgrade nervapack

pipx¶

pipx upgrade nervapack

pip¶

pip install --upgrade nervapack

Check your version:

nervapack --version
# or
pip show nervapack

Uninstalling¶

Homebrew¶

brew uninstall nervapack

pipx¶

pipx uninstall nervapack

pip¶

pip uninstall nervapack

To remove all NervaPack data (graphs, caches):

# Remove project-specific graphs
rm -rf .nervapack/

# Remove ChromaDB cache (optional)
rm -rf ~/.cache/chroma

Corporate / Air-Gapped Environments¶

NervaPack's vector search uses the all-MiniLM-L6-v2 ONNX model (86 MB), which ChromaDB downloads from an AWS S3 bucket on first use. If your corporate network blocks external downloads, follow one of these approaches:

Option A — Pre-copy the model (recommended)¶

Transfer the model from a machine that has internet access:

Step 1: On a machine with internet access, run any nervapack ingest or nervapack query to trigger the download. The model is cached at:

~/.cache/chroma/onnx_models/all-MiniLM-L6-v2/

Step 2: Zip the model folder:

tar -czf nervapack-onnx-model.tar.gz \
    -C ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2 onnx

Step 3: Copy nervapack-onnx-model.tar.gz to your corporate machine via USB, internal file share, or any approved transfer method.

Step 4: On the corporate machine, restore the model:

mkdir -p ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2
tar -xzf nervapack-onnx-model.tar.gz \
    -C ~/.cache/chroma/onnx_models/all-MiniLM-L6-v2

That's it — nervapack ingest . and nervapack query now work with no internet access. ChromaDB finds the model in the standard cache path and skips the download.

Option B — Point to a shared network drive¶

If your team has a shared drive, place the model there once and point NervaPack to it via an environment variable:

# Place the model folder on a shared drive, e.g.:
# \\corp-share\tools\nervapack-onnx\all-MiniLM-L6-v2\onnx\

# On each developer machine, set:
export NERVAPACK_ONNX_MODEL=/mnt/corp-share/tools/nervapack-onnx/all-MiniLM-L6-v2

# Add to ~/.bashrc or ~/.zshrc to persist:
echo 'export NERVAPACK_ONNX_MODEL=/mnt/corp-share/tools/nervapack-onnx/all-MiniLM-L6-v2' >> ~/.bashrc

NervaPack reads NERVAPACK_ONNX_MODEL at startup and loads the model directly from that path — no download, no cache needed.

Option C — Use Ollama embeddings¶

If Ollama is available on your corporate network (or internally hosted):

nervapack ingest . --embeddings ollama

Set permanently via environment variable:

export NERVAPACK_EMBEDDINGS=ollama

Ollama must be reachable at http://localhost:11434 (the default). If it's on a different host, contact us — support for a custom Ollama host URL is on the roadmap.

Troubleshooting Installation¶

Python version errors¶

ERROR: Package requires Python 3.10 or higher

Solution: Install Python 3.10+ from python.org

Permission errors on macOS¶

WARNING: The directory '/Users/xxx/Library/Caches/pip' is not owned by you

Solution: Use --user flag:

pip install --user nervapack

Or use pipx (recommended).

Dependency conflicts¶

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed

Solution: Use pipx for isolated installation, or create a virtual environment:

python -m venv nervapack-env
source nervapack-env/bin/activate  # On Windows: nervapack-env\Scripts\activate
pip install nervapack

tree-sitter compilation errors¶

Rare on modern systems. If you encounter this:

Ensure you have a C compiler:
- macOS: xcode-select --install
- Linux: sudo apt install build-essential (Debian/Ubuntu)
- Windows: Install Visual Studio Build Tools
Retry installation

Next Steps¶

Now that NervaPack is installed, let's set up your LLM provider:

LLM Provider Setup →

Or jump straight to the quick start tutorial:

Quick Start Tutorial →