Skip to content

Configuration

QuranKit can be configured through environment variables, a configuration file, or programmatically.

Environment Variables

Variable Description Default
QURANKIT_DATA_DIR Root directory for dataset storage ~/.local/share/qurankit
QURANKIT_DEFAULT_EDITION Default text edition to load First available edition
QURANKIT_CACHE_DIR Cache directory for computed results ~/.cache/qurankit
# Set custom data directory
export QURANKIT_DATA_DIR=/path/to/qurankit-data

# Set default edition
export QURANKIT_DEFAULT_EDITION=tanzil-simple

Configuration File

Create a config.toml file in your data directory:

# ~/.local/share/qurankit/config.toml

[data]
dir = "/path/to/qurankit-data"

[quran]
default_edition = "tanzil-simple"
auto_load = true

[search]
default_mode = "broad"
max_results = 1000

[cache]
enabled = true
dir = "~/.cache/qurankit"
max_size_mb = 500

[cli]
color = true
pager = "auto"

Programmatic Configuration

from qurankit import Quran, QuranKitConfig

# Create custom config
config = QuranKitConfig(
    data_dir="/path/to/qurankit-data",
    default_edition="tanzil-uthmani",
    cache_enabled=True,
    cache_dir="/path/to/cache"
)

# Load with custom config
quran = Quran.load(config=config)

# Or modify after loading
quran.config.default_edition = "tanzil-uthmani"

Data Directory Structure

qurankit-data/
├── config.toml              # Configuration file
├── datasets/                # Installed datasets
│   ├── tanzil/
│   │   ├── simple/
│   │   │   ├── 1.0.0/
│   │   │   │   ├── manifest.json
│   │   │   │   ├── text.xml
│   │   │   │   └── metadata.json
│   │   │   └── latest -> 1.0.0
│   │   └── uthmani/
│   │       └── ...
│   └── qac/
│       └── 2.0/
│           ├── manifest.json
│           └── morphology.xml
├── registry.json            # Dataset registry
└── cache/                   # Computed caches
    ├── search_index.db
    └── vocabulary.db

Dataset Registry

The dataset registry tracks installed datasets:

from qurankit import Quran

quran = Quran.load()

# View registry
registry = quran.registry
for dataset_id, info in registry.list_datasets().items():
    print(f"{dataset_id}: {info.version} ({info.status})")

# Check if dataset is installed
if registry.is_installed("tanzil", "simple", "1.0.0"):
    print("Tanzil simple edition installed")

Search Configuration

from qurankit import Quran
from qurankit.search import NormalizationProfile

quran = Quran.load()

# Get available normalization profiles
profiles = quran.get_normalization_profiles()
print("Available profiles:", profiles)

# Set default search mode
quran.config.search.default_mode = "diacritic_insensitive"

# Custom normalization (advanced)
from qurankit.search.normalization import NormalizationEngine

engine = NormalizationEngine()
custom_profile = engine.create_profile(
    name="custom",
    remove_diacritics=True,
    normalize_hamza=True,
    normalize_ya_maqsurah=True,
    keep_quranic_marks=False
)

Cache Management

from qurankit import Quran

quran = Quran.load()

# Clear search cache
quran.clear_search_cache()

# Clear vocabulary cache
quran.clear_vocabulary_cache()

# Clear all caches
quran.clear_all_caches()

# Get cache statistics
stats = quran.get_cache_stats()
print(f"Search cache: {stats.search_cache_mb} MB")
print(f"Vocabulary cache: {stats.vocab_cache_mb} MB")

Logging Configuration

import logging

# Enable debug logging for QuranKit
logging.getLogger("qurankit").setLevel(logging.DEBUG)

# Or configure via environment
# export QURANKIT_LOG_LEVEL=DEBUG

Next Steps