Installation

Install OpenGround with the right backend for your system

Installation

OpenGround can be installed with different embedding backends depending on your needs and hardware.

Prerequisites

• Python 3.10, 3.11, or 3.12
• pip or uv package manager
• Git (for cloning documentation repositories)

Python 3.13 is not yet supported due to dependencies. Use Python 3.10-3.12.

Installation Methods

Recommended: Install with uv

uv is the fastest Python package installer. Choose the variant that matches your hardware:

Full Support (Recommended)

Includes sentence-transformers with automatic GPU/MPS/CPU detection:

uv tool install openground

Pros:

• Automatic hardware detection (GPU, MPS, CPU)
• Best performance on all platforms
• Most tested and stable

Cons:

• Larger package size (~2GB)
• Longer installation time

Lightweight CPU

Uses fastembed for CPU-only workloads:

uv tool install 'openground[fastembed]'

Pros:

• Smaller package size (~200MB)
• Faster installation
• Lower memory usage

Cons:

• CPU-only, no GPU acceleration
• Slightly slower embedding generation

Experimental GPU

Uses fastembed with CUDA support:

uv tool install 'openground[fastembed-gpu]'

This variant is experimental. Requires CUDA drivers and cuDNN to be properly installed.

Pros:

• Smaller than sentence-transformers
• GPU acceleration for embeddings

Cons:

• Requires CUDA setup
• Less stable than sentence-transformers GPU
• May not work out of the box

Alternative: Install with pip

If you don’t use uv, you can install with pip:

Full Support

pip install openground

Backend Comparison

Feature	sentence-transformers	fastembed	fastembed-gpu
Package Size	~2GB	~200MB	~500MB
GPU Support	✅ CUDA, MPS, CPU	❌ CPU only	✅ CUDA only
Stability	⭐⭐⭐	⭐⭐⭐	⭐⭐
Speed (GPU)	Fast	N/A	Fast
Speed (CPU)	Medium	Fast	N/A

Use the default openground package unless you have specific constraints. It provides the best experience across all hardware.

Verify Installation

After installation, verify that OpenGround is working:

1. Check version

   openground version
   

   You should see a version number like 0.13.0.

2. View help

   openground --help
   

   This displays all available commands.

3. Check configuration

   openground config show
   

   This creates a default configuration file and displays it.

GPU Setup (Optional)

If you installed the default package or fastembed-gpu variant, you may want to verify GPU support.

NVIDIA GPU (CUDA)

1. Check NVIDIA drivers

   nvidia-smi
   

   This should show your GPU information. If this fails, install NVIDIA drivers first.

2. For fastembed-gpu: Verify CUDA

   The fastembed-gpu variant requires CUDA 11.x or 12.x with matching cuDNN:

   • CUDA Toolkit Installation
   • cuDNN Installation

   See ONNX Runtime CUDA requirements for compatibility.

3. For sentence-transformers: Verify PyTorch

   python -c "import torch; print(torch.cuda.is_available())"
   

   This should print True if CUDA is working.

Apple Silicon (MPS)

The default package (sentence-transformers) automatically uses Apple’s Metal Performance Shaders on M1/M2/M3 Macs:

python -c "import torch; print(torch.backends.mps.is_available())"

Should print True on Apple Silicon Macs.

fastembed and fastembed-gpu do not support Apple Silicon GPU acceleration. Use the default package for MPS support.

Troubleshooting

ModuleNotFoundError: No module named 'openground'

The package is not installed in your current Python environment.

Solution:

• If using uv: Make sure you used uv tool install not uv pip install
• If using pip: Try python -m pip install openground
• Verify with which openground or where openground (Windows)

GPU detected but CUDA is not functional

You have an NVIDIA GPU but CUDA is not working.

Solution for fastembed-gpu:

1. Ensure CUDA 11.x or 12.x is installed
2. Install matching cuDNN version
3. Verify with python -c "import onnxruntime as ort; print(ort.get_available_providers())"
4. Should include ‘CUDAExecutionProvider’

Solution for sentence-transformers:

1. Reinstall PyTorch with CUDA support:
   pip install torch --index-url https://download.pytorch.org/whl/cu121
   
2. Verify with python -c "import torch; print(torch.cuda.is_available())"

Installation takes forever

The default package includes PyTorch and sentence-transformers which are large.

Solutions:

• Use openground[fastembed] for a lighter install
• Ensure you have a good internet connection
• The download is large but only happens once

Permission denied on Windows

Windows may require administrator privileges.

Solution:

• Run your terminal as administrator
• Or use --user flag: pip install --user openground

Switching Backends

If you want to switch backends after installation, see the Embedding Backends guide.

Switching backends requires re-embedding all your documentation. Existing databases are not compatible across backends.

Upgrading

To upgrade to the latest version:

uv

uv tool upgrade openground

Uninstalling

To remove OpenGround:

uv

uv tool uninstall openground

Uninstalling does not remove your configuration or embedded documentation. To remove all data, run openground nuke all before uninstalling.

Next Steps

Quickstart

Get started in 5 minutes

Add Documentation

Add your first documentation library

Configuration

Customize OpenGround settings

MCP Integration

Connect to AI coding assistants