Installation Guide - mySpellChecker

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)

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

import myspellchecker
print(myspellchecker.__version__)

# 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

# Build sample database for testing
myspellchecker build --sample

Building from Corpus

# Build from your own corpus
myspellchecker build --input corpus.txt --output dictionary.db

See Data Pipeline for detailed dictionary building instructions.

Installation Options

With AI/Semantic Features

For deep learning-based context checking:

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

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

pip install myspellchecker[ai-full]

Combines: ai + transformers

With Dictionary Building Tools

For building custom dictionaries from corpora:

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:

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:

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)

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

# Install Python and build tools
sudo dnf install python3-devel python3-pip gcc gcc-c++

# Install mySpellChecker
pip install myspellchecker

macOS

# 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

# 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

# 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

# Create conda environment
conda create -n myspell python=3.11

# Activate
conda activate myspell

# Install
pip install myspellchecker

Using Poetry

# 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

# 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

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

# Rebuild extensions
python setup.py build_ext --inplace

Troubleshooting Cython Build

Missing C++ Compiler:

# Linux
sudo apt install build-essential

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools

OpenMP Not Found (macOS):

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:

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:

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:

myspellchecker build --sample

Issue: “Cython extension failed to compile”

Solution: Install a C++ compiler:

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

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

# 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

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

Next Steps

Dictionary Building - Build a dictionary database (required before spell checking)
Quick Start - Learn the basics in 5 minutes
Configuration - Customize behavior

​Basic Installation

​Using pip (Recommended)

​Verify Installation

​Dictionary Database

​Providing a Database

​Building a Sample Database

​Building from Corpus

​Installation Options

​With AI/Semantic Features

​With Transformer POS Tagger

​Full Installation

​With Dictionary Building Tools

​With Model Training

​Development Installation

​Platform-Specific Instructions

​Linux (Ubuntu/Debian)

​Linux (RHEL/CentOS/Fedora)

​macOS

​Windows

​Virtual Environment Setup

​Using venv

​Using conda

​Using Poetry

​Building from Source

​Clone and Install

​Development Dependencies

​Running Tests

​Cython Extension Compilation

​Troubleshooting Cython Build

​Verifying Installation

​Common Issues

​Issue: “No module named ‘myspellchecker’”

​Issue: “Database not found”

​Issue: “Cython extension failed to compile”

​Issue: “OpenMP not found” (macOS)

​Docker Installation

​Quick Start with Docker Compose

​Available Docker Services

​Building Docker Images

​Next Steps

Basic Installation

Using pip (Recommended)

Verify Installation

Dictionary Database

Providing a Database

Building a Sample Database

Building from Corpus

Installation Options

With AI/Semantic Features

With Transformer POS Tagger

Full Installation

With Dictionary Building Tools

With Model Training

Development Installation

Platform-Specific Instructions

Linux (Ubuntu/Debian)

Linux (RHEL/CentOS/Fedora)

macOS

Windows

Virtual Environment Setup

Using venv

Using conda

Using Poetry

Building from Source

Clone and Install

Development Dependencies

Running Tests

Cython Extension Compilation

Troubleshooting Cython Build

Verifying Installation

Common Issues

Issue: “No module named ‘myspellchecker’”

Issue: “Database not found”

Issue: “Cython extension failed to compile”

Issue: “OpenMP not found” (macOS)

Docker Installation

Quick Start with Docker Compose

Available Docker Services

Building Docker Images

Next Steps