Installation

Install NeMo Guardrails and get started adding programmable guardrails to your LLM applications

Prerequisites

Before installing NeMo Guardrails, ensure your system meets the following requirements:

Python Version

NeMo Guardrails supports the following Python versions:

• Python 3.10
• Python 3.11
• Python 3.12
• Python 3.13

Python 3.9 and earlier versions are not supported.

C++ Compiler and Dev Tools

NeMo Guardrails uses annoy, a C++ library with Python bindings for efficient similarity search. You’ll need a C++ compiler and development tools installed on your system.

macOS

Install Xcode Command Line Tools:

xcode-select --install

This provides the necessary C++ compiler (clang) and build tools.

Linux (Ubuntu/Debian)

Install build essentials:

sudo apt-get update
sudo apt-get install build-essential python3-dev

Linux (RHEL/CentOS/Fedora)

Install development tools:

sudo yum groupinstall "Development Tools"
sudo yum install python3-devel

Windows

Install Microsoft Visual C++ 14.0 or greater:

1. Download and install Microsoft C++ Build Tools
2. During installation, select “Desktop development with C++”

Alternatively, install Visual Studio 2019 or later with C++ support.

Installation

1. Install via pip

   The simplest way to install NeMo Guardrails is using pip:

   pip install nemoguardrails
   

   This installs the core package with all essential dependencies.

2. Verify Installation

   Verify that NeMo Guardrails is installed correctly:

   nemoguardrails --help
   

   You should see the help menu with available commands:

   Usage: nemoguardrails [OPTIONS] COMMAND [ARGS]...
   
   Commands:
     actions-server    Start a NeMo Guardrails actions server.
     chat              Start an interactive chat session.
     evaluate          Run an evaluation task.
     server            Start a NeMo Guardrails server.
   
3. Test Python Import

   Test that you can import the package in Python:

   from nemoguardrails import LLMRails, RailsConfig
   print("NeMo Guardrails installed successfully!")
   

   If this runs without errors, you’re ready to go!

Optional Dependencies

NeMo Guardrails supports optional features through extras. Install them based on your needs:

OpenAI Support

pip install "nemoguardrails[openai]"

Optional Dependencies Details

openai - OpenAI and LangChain OpenAI Support

Includes:

• openai - Official OpenAI Python client
• langchain-openai - LangChain integrations for OpenAI models

Required for using OpenAI models (GPT-3.5, GPT-4, etc.).

eval - Evaluation and Benchmarking Tools

Includes:

• tqdm - Progress bars for evaluation
• numpy - Numerical computing
• streamlit - Web UI for evaluation results
• tornado - Web server framework

Required for running nemoguardrails evaluate command.

sdd - Sensitive Data Detection

Includes:

• presidio-analyzer - PII detection and analysis
• presidio-anonymizer - PII anonymization

Required for detecting and masking sensitive data like emails, phone numbers, SSNs, etc.

Not available for Python 3.13

gcp - Google Cloud Platform Integration

Includes:

• google-cloud-language - Google Cloud Natural Language API

Required for using Google Cloud services.

nvidia - NVIDIA AI Endpoints

Includes:

• langchain-nvidia-ai-endpoints - LangChain integration for NVIDIA NIM

Required for using NVIDIA NIM (NVIDIA Inference Microservices).

tracing - OpenTelemetry Tracing

Includes:

• opentelemetry-api - OpenTelemetry API
• aiofiles - Async file operations

Required for distributed tracing and observability.

jailbreak - Jailbreak Detection

Includes:

• yara-python - Pattern matching for jailbreak detection

Required for advanced jailbreak attempt detection.

multilingual - Language Detection

Includes:

• fast-langdetect - Fast language detection

Required for multilingual content safety.

server - Server Features

Includes:

• aiofiles - Async file operations
• openai - OpenAI client for server endpoints

Required for running nemoguardrails server with full features.

Development Installation

For contributing to NeMo Guardrails or running tests, install from source:

1. Clone the Repository

   git clone https://github.com/NVIDIA-NeMo/Guardrails.git
   cd Guardrails
   
2. Install with Poetry

   NeMo Guardrails uses Poetry for dependency management:

   pip install poetry
   poetry install --with dev
   
3. Activate the Environment

   poetry shell
   
4. Run Tests

   pytest
   

Docker Installation

You can also run NeMo Guardrails in a Docker container:

# Build the image
docker build -t nemoguardrails .

# Run the server
docker run -p 8000:8000 -v $(pwd)/config:/config nemoguardrails \
  nemoguardrails server --config /config

For detailed Docker usage, see the Using Docker guide in the official documentation.

Environment Variables

For using LLM providers, you’ll typically need API keys set as environment variables:

OpenAI

export OPENAI_API_KEY="your-api-key-here"

Anthropic

export ANTHROPIC_API_KEY="your-api-key-here"

Cohere

export COHERE_API_KEY="your-api-key-here"

Troubleshooting

Error: Microsoft Visual C++ 14.0 or greater is required

Windows users: Install Microsoft C++ Build Tools as described in the prerequisites section.

Error: command 'gcc' failed

Linux/macOS users: Install build tools and Python development headers:

Ubuntu/Debian

sudo apt-get install build-essential python3-dev

macOS

xcode-select --install

ImportError: No module named 'annoy'

The annoy library didn’t install correctly. This usually means the C++ compiler isn’t available. Install the required build tools for your platform.

Version conflicts with existing packages

Consider using a virtual environment to isolate dependencies:

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

Next Steps

Quickstart Guide

Now that you have NeMo Guardrails installed, follow the quickstart guide to create your first guardrails configuration.