Skip to main content
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

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:
ToolPurpose
pytestTesting framework
pytest-covCoverage reporting
pytest-benchmarkPerformance benchmarks
ruffLinting and formatting
mypyStatic 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

ServiceCommandDescription
apidocker compose up apiProduction API server
devdocker compose --profile dev up devDevelopment with hot reload
clidocker compose --profile cli run --rm cli check "မြန်မာစာ"CLI tool
testdocker compose --profile test run --rm testRun tests
api-gpudocker compose --profile gpu up api-gpuGPU-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