Skip to content

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):

Installation Methods

The easiest way to install on macOS or Linux:

brew tap ramdhavepreetam/nervapack
brew install nervapack

Verify installation: 

nervapack --help

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 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]"

First-Time Setup

On first run, NervaPack will:

  1. Download ChromaDB models (~1-2 minutes, one-time)

    • ONNX runtime embedding models
    • Stored in your system cache

  2. 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

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:

  1. Ensure you have a C compiler:

    • macOS: xcode-select --install
    • Linux: sudo apt install build-essential (Debian/Ubuntu)
    • Windows: Install Visual Studio Build Tools

  2. 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 →