Installation¶

This section describes how to install the HMB Helpers Package and its dependencies.

Prerequisites¶

Python 3.8 or higher
pip package manager
Optional: CUDA-compatible GPU for GPU acceleration

Installation Methods¶

Quick install

Recommended quick installs:

From PyPI (recommended): pip install hmb-helpers — https://pypi.org/project/hmb-helpers/
From GitHub (development): pip install git+https://github.com/HossamBalaha/HMB-Helpers-Package.git

From PyPI (Recommended)¶

Install the latest released version from PyPI (recommended for most users):

pip install hmb-helpers

Install with optional feature groups (examples):

# Computer vision & PyTorch.
pip install "hmb-helpers[cv,pytorch]"

# NLP & text processing.
pip install "hmb-helpers[nlp]"

# PDF handling.
pip install "hmb-helpers[pdf]"

# Full installation (most optional dependencies)
# Note: The `all` extra installs most optional dependencies but intentionally
# excludes large, platform- and device-specific frameworks (PyTorch, TensorFlow,
# Keras and related runtime packages). Install those frameworks separately
# using the dedicated extras below or via the framework's official installer.
pip install "hmb-helpers[all]"

For CUDA-enabled PyTorch wheels, install the package then replace the CPU wheels with the CUDA-specific wheels that match your system (see PyTorch instructions below).

Project page on PyPI: https://pypi.org/project/hmb-helpers/

From GitHub (Development Version)¶

Install the latest development version directly from GitHub:

pip install git+https://github.com/HossamBalaha/HMB-Helpers-Package.git

Editable Install (For Development)¶

If you plan to modify the package source code:

git clone https://github.com/HossamBalaha/HMB-Helpers-Package.git
cd HMB-Helpers-Package
pip install -e ".[dev]"

Installing Dependencies¶

Core dependencies are listed in requirements.txt. Install them with:

pip install -r requirements.txt

The core runtime dependencies (also reflected in setup.py) include recent minima such as:

numpy>=1.26.4,<2
pillow>=12.2.0
pyyaml>=6.0.3
pandas>=3.0.2
matplotlib>=3.9
tqdm>=4.67.3
scikit-learn>=1.8.0

Optional Dependencies¶

Install optional feature groups via extras:

# Scientific computing stack
pip install "hmb-helpers[scientific]"

# Computer vision & image processing
pip install "hmb-helpers[cv]"

# PyTorch deep learning (CPU wheels)
pip install "hmb-helpers[pytorch]"

# TensorFlow deep learning
pip install "hmb-helpers[tensorflow]"

# NLP & text processing (includes Arabic support)
pip install "hmb-helpers[nlp]"

# PDF handling with table extraction
pip install "hmb-helpers[pdf]"

# Audio processing & feature extraction
pip install "hmb-helpers[audio]"

# Medical imaging & whole slide images
pip install "hmb-helpers[medical]"

# Classical ML models & optimization
pip install "hmb-helpers[ml]"

# Visualization & plotting
pip install "hmb-helpers[plotting]"

# All optional dependencies (most; excludes heavy frameworks)
# Note: `all` omits PyTorch/TensorFlow/Keras to avoid accidental large/platform-specific installs.
pip install "hmb-helpers[all]"

Download required NLTK data after installing the nlp extra:

python -c "import nltk; nltk.download('punkt'); nltk.download('stopwords'); nltk.download('wordnet')"

For spaCy models:

python -m spacy download en_core_web_sm
# For Arabic: python -m spacy download xx_ent_wiki_sm

CUDA/PyTorch GPU Support¶

The pytorch extra installs CPU-compatible PyTorch wheels by default. For GPU acceleration:

Install the package with PyTorch support:
```
pip install "hmb-helpers[pytorch]"
```

Replace with CUDA-specific wheels matching your system:

pip uninstall torch torchvision torchaudio -y
pip install torch==2.7.1+cu128 torchvision==0.22.1+cu128 torchaudio==2.7.1+cu128 \
  --extra-index-url https://download.pytorch.org/whl/cu128

Tip

For step-by-step guidance tailored to your operating system, package manager, and CUDA version, visit the official PyTorch installation selector: https://pytorch.org/get-started/locally/

Note

TensorFlow GPU support requires separate installation. See https://www.tensorflow.org/install for platform-specific instructions.

Verifying Installation¶

After installation, verify the package and optional features:

import HMB
print(f"Package version: {HMB.__version__}")  # Should print: 0.2.0

# Test core functionality.
from HMB.ImagesHelper import GetEmptyPercentage
print("✓ Core images module loaded")

# Test optional feature (will raise ImportError if not installed).
try:
  from HMB.PDFHelper import ReadFullPDF
  print("✓ PDF module available")
except ImportError:
  print("⚠ PDF module: install with pip install 'hmb-helpers[pdf]'")

Troubleshooting¶

Import errors: Ensure you installed in the same virtual environment you are using.
Missing native libraries: For openslide or tabula-py, install system-level dependencies first (see upstream docs).
Dependency conflicts: Use a fresh virtualenv or conda environment.
NLTK/spaCy models: After installing the nlp extra, download required models as shown above.

Tip

For step-by-step guidance tailored to your operating system and CUDA version, visit the official PyTorch installation selector: https://pytorch.org/get-started/locally/