Installation¶
Requirements¶
- Python 3.12 or higher
- pip (Python package installer)
Basic Installation¶
Optional Dependencies¶
QuranKit uses optional dependency groups for features that require additional packages:
| Extra | Purpose | Packages |
|---|---|---|
cli |
Command-line interface | click, rich |
tanzil |
Tanzil text dataset downloader | requests |
qac |
QAC morphology provider | lxml |
mcp |
MCP (Model Context Protocol) server | mcp |
dev |
Development tools | pytest, ruff, mypy |
Install with extras¶
# For CLI usage
pip install "qurankit-core[cli]"
# For Tanzil dataset downloading
pip install "qurankit-core[tanzil]"
# For full development environment
pip install "qurankit-core[cli,tanzil,qac,mcp,dev]"
# Or install everything
pip install "qurankit-core[all]"
Installing from Source¶
Verifying Installation¶
# Check package version
python -c "import qurankit; print(qurankit.__version__)"
# Check available CLI commands (if cli extra installed)
qurankit --help
Dataset Installation¶
QuranKit does not bundle Qur'anic text datasets due to licensing. You must install datasets separately:
Tanzil Text Edition (CC-BY-3.0)¶
# Download and install Tanzil text
qurankit dataset install tanzil --edition simple --version 1.0.0
# Or with specific edition
qurankit dataset install tanzil --edition uthmani --version 1.0.0
QAC Morphology (GPL + Non-commercial FAQ)¶
Licensing
- Tanzil: CC-BY-3.0 — Attribution required, verbatim text only
- QAC: GPL + FAQ non-commercial restriction — Optional adapter only
- See Dataset Evaluation for full details
Offline Usage¶
After datasets are installed, QuranKit works completely offline:
from qurankit import Quran
# No network access required
quran = Quran.load() # Uses locally installed datasets
Troubleshooting¶
Package not found¶
If you get ModuleNotFoundError: No module named 'qurankit', ensure:
- You're using the correct package name:
qurankit-coreon PyPI, but import asqurankit - Your virtual environment is activated
- The package is installed:
pip list | grep qurankit
Dataset not found¶
If Quran.load() fails with dataset not found:
- Run
qurankit dataset listto see available datasets - Install a dataset:
qurankit dataset install tanzil - Check data directory:
qurankit config show
Permission errors¶
If you get permission errors during dataset installation:
# Use a custom data directory
export QURANKIT_DATA_DIR=~/qurankit-data
qurankit dataset install tanzil