> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Guide

> This guide covers all installation methods for mySpellChecker, from basic pip installation to development setup with all optional features.

Choose the installation method that fits your needs, from a minimal pip install for basic spell checking to a full development setup with Cython acceleration, transformer models, and ONNX inference.

## Basic Installation

### Using pip (Recommended)

```bash theme={null}
pip install myspellchecker
```

This installs the core library with all essential features:

* Syllable validation
* Word validation with SymSpell
* Context checking with N-grams
* SQLite dictionary provider
* CLI tools

### Verify Installation

```python theme={null}
import myspellchecker
print(myspellchecker.__version__)
```

```bash theme={null}
# Or via CLI
myspellchecker --help
```

## Dictionary Database

mySpellChecker requires a dictionary database for spell checking. **No bundled database is included**, so you must build one first.

### Providing a Database

Pass the database path explicitly:

* Use `SQLiteProvider(database_path="/path/to/db.db")`
* Or use CLI flag: `myspellchecker check --db /path/to/db.db`
* Or set in config file: `database: /path/to/db.db`
* Or set environment variable: `MYSPELL_DATABASE_PATH` (via ConfigLoader)

### Building a Sample Database

```bash theme={null}
# Build sample database for testing
myspellchecker build --sample
```

### Building from Corpus

```bash theme={null}
# Build from your own corpus
myspellchecker build --input corpus.txt --output dictionary.db
```

See [Data Pipeline](/data-pipeline/index) for detailed dictionary building instructions.

## Installation Options

### With AI/Semantic Features

For deep learning-based context checking:

```bash theme={null}
pip install myspellchecker[ai]
```

This adds:

* ONNX Runtime for semantic model inference
* Tokenizers library for fast text tokenization
* Pre-trained semantic models support

### With Transformer POS Tagger

For highest accuracy POS tagging (\~93%):

```bash theme={null}
pip install myspellchecker[transformers]
```

This adds:

* PyTorch
* Hugging Face Transformers
* Pre-trained Myanmar POS models support

### Full Installation

Install complete AI features (Semantic + Transformer POS):

```bash theme={null}
pip install myspellchecker[ai-full]
```

Combines: `ai` + `transformers`

### With Dictionary Building Tools

For building custom dictionaries from corpora:

```bash theme={null}
pip install myspellchecker[build]
```

This adds:

* PyArrow for columnar data processing
* DuckDB for fast pipeline aggregations
* xxhash for deduplication hashing
* tqdm for progress bars
* cached-path for resource downloading

### With Model Training

For training custom semantic and POS models:

```bash theme={null}
pip install myspellchecker[train]
```

This adds:

* PyTorch
* Hugging Face Transformers
* Datasets for data loading
* Accelerate for distributed training
* ONNX and ONNX Runtime for model export
* onnxscript for torch ONNX export
* Tokenizers for BPE tokenizer training

### Development Installation

For contributors and developers:

```bash theme={null}
pip install myspellchecker[dev]
```

This adds:

* pytest and testing tools
* ruff for linting/formatting
* mypy for type checking
* Note: Cython is automatically installed as a build dependency, not part of the \[dev] extra.

## Platform-Specific Instructions

### Linux (Ubuntu/Debian)

```bash theme={null}
# Install Python and build tools
sudo apt update
sudo apt install python3-dev python3-pip build-essential

# Install mySpellChecker
pip install myspellchecker
```

### Linux (RHEL/CentOS/Fedora)

```bash theme={null}
# Install Python and build tools
sudo dnf install python3-devel python3-pip gcc gcc-c++

# Install mySpellChecker
pip install myspellchecker
```

### macOS

```bash theme={null}
# Using Homebrew
brew install python

# For OpenMP parallelization support (optional but recommended)
brew install libomp

# Install mySpellChecker
pip install myspellchecker
```

**Note**: Without `libomp`, Cython extensions will compile without parallel processing. The library will still work but batch processing will be single-threaded.

### Windows

```powershell theme={null}
# Ensure Python is installed and in PATH
python --version

# Install Visual Studio Build Tools for Cython (if needed)
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

# Install mySpellChecker
pip install myspellchecker
```

## Virtual Environment Setup

We recommend using a virtual environment:

### Using venv

```bash theme={null}
# Create virtual environment
python -m venv myspell-env

# Activate (Linux/macOS)
source myspell-env/bin/activate

# Activate (Windows)
myspell-env\Scripts\activate

# Install
pip install myspellchecker
```

### Using conda

```bash theme={null}
# Create conda environment
conda create -n myspell python=3.11

# Activate
conda activate myspell

# Install
pip install myspellchecker
```

### Using Poetry

```bash theme={null}
# Add to project
poetry add myspellchecker

# With optional features
poetry add myspellchecker[ai,transformers]
```

## Building from Source

For development or to get the latest features:

### Clone and Install

```bash theme={null}
# Clone repository
git clone https://github.com/thettwe/myspellchecker.git
cd my-spellchecker

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Build Cython extensions
python setup.py build_ext --inplace
```

### Development Dependencies

The development installation includes:

| Tool             | Purpose                |
| ---------------- | ---------------------- |
| pytest           | Testing framework      |
| pytest-cov       | Coverage reporting     |
| pytest-benchmark | Performance benchmarks |
| ruff             | Linting and formatting |
| mypy             | Static type checking   |

> **Note**: Cython is automatically installed as a build-system dependency (specified in `pyproject.toml` build requirements), not as part of the `[dev]` extra.

### Running Tests

```bash theme={null}
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=myspellchecker --cov-report=html

# Run specific test category
pytest tests/ -m unit
pytest tests/ -m integration
```

## Cython Extension Compilation

Cython extensions provide significant performance improvements. They're automatically compiled during installation, but if you modify `.pyx` files:

```bash theme={null}
# Rebuild extensions
python setup.py build_ext --inplace
```

### Troubleshooting Cython Build

**Missing C++ Compiler**:

```bash theme={null}
# Linux
sudo apt install build-essential

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools
```

**OpenMP Not Found (macOS)**:

```bash theme={null}
brew install libomp
```

If OpenMP installation fails, the library will compile with single-threaded extensions (graceful degradation).

## Verifying Installation

Run this script to verify all components are installed correctly:

```python theme={null}
from myspellchecker import SpellChecker
from myspellchecker.providers import SQLiteProvider

# Check core installation
print("Core library: OK")

# Check provider
try:
    provider = SQLiteProvider()  # Will warn if no database path is configured
    print("SQLite Provider: OK")
except Exception as e:
    print(f"SQLite Provider: WARNING - {e}")

# Check Cython extensions
try:
    from myspellchecker.text.normalize_c import remove_zero_width_chars
    print("Cython extensions: OK")
except ImportError:
    print("Cython extensions: NOT AVAILABLE (install from wheel or compile)")

# Check AI features
try:
    import onnxruntime
    print("AI features (ONNX): OK")
except ImportError:
    print("AI features (ONNX): NOT INSTALLED")

# Check transformer features
try:
    import transformers
    print("Transformer POS: OK")
except ImportError:
    print("Transformer POS: NOT INSTALLED")

# Check DuckDB (optional - needed for dictionary building)
try:
    import duckdb
    print(f"DuckDB: OK (version {duckdb.__version__})")
except ImportError:
    print("DuckDB: NOT INSTALLED (install with: pip install myspellchecker[build])")
```

## Common Issues

### Issue: "No module named 'myspellchecker'"

**Solution**: Ensure you're in the correct virtual environment:

```bash theme={null}
which python  # Should show your venv path
pip show myspellchecker  # Should show installation info
```

### Issue: "Database not found"

**Solution**: Build or download a dictionary database:

```bash theme={null}
myspellchecker build --sample
```

### Issue: "Cython extension failed to compile"

**Solution**: Install a C++ compiler:

```bash theme={null}
# Linux
sudo apt install build-essential

# macOS
xcode-select --install
```

Cython extensions provide performance improvements but are not strictly required. The library falls back to pure Python implementations if Cython is unavailable.

### Issue: "OpenMP not found" (macOS)

**Solution**: Install libomp:

```bash theme={null}
brew install libomp
```

This is optional - the library works without OpenMP but uses single-threaded processing.

## Docker Installation

For containerized deployments, mySpellChecker provides Docker support with multi-stage builds.

### Quick Start with Docker Compose

```bash theme={null}
# Clone the repository
git clone https://github.com/thettwe/myspellchecker.git
cd my-spellchecker

# Start the API server
docker compose up api

# The API is now available at http://localhost:8000
```

### Available Docker Services

| Service   | Command                                                      | Description                 |
| --------- | ------------------------------------------------------------ | --------------------------- |
| `api`     | `docker compose up api`                                      | Production API server       |
| `dev`     | `docker compose --profile dev up dev`                        | Development with hot reload |
| `cli`     | `docker compose --profile cli run --rm cli check "မြန်မာစာ"` | CLI tool                    |
| `test`    | `docker compose --profile test run --rm test`                | Run tests                   |
| `api-gpu` | `docker compose --profile gpu up api-gpu`                    | GPU-enabled API             |

### Building Docker Images

```bash theme={null}
# Build production image
docker build --target runtime -t myspellchecker:latest .

# Build CLI-only image
docker build --target cli -t myspellchecker:cli .
```

For detailed Docker configuration, see the [Docker Guide](/guides/docker).

## Next Steps

* **[Dictionary Building](/data-pipeline/index)** - Build a dictionary database (required before spell checking)
* **[Quick Start](/guides/quickstart)** - Learn the basics in 5 minutes
* **[Configuration](/guides/configuration)** - Customize behavior