Installation

Important

Requirements: Python 3.10+ | PyTorch 2.2+ (auto-installed)

Quick Install

pip install deeptab

This installs DeepTab with all dependencies including PyTorch, Lightning, and preprocessing tools.

Verify installation:

import deeptab
print(deeptab.__version__)  # e.g., "2.0.0"

Optional Dependencies

The default install keeps the core small. Observability backends (structured logging and experiment trackers) ship as extras, so install only what you need:

pip install 'deeptab[logs]'         # structlog (structured logging)
pip install 'deeptab[tensorboard]'  # TensorBoard tracker
pip install 'deeptab[mlflow]'       # MLflow tracker
pip install 'deeptab[tracking]'     # TensorBoard + MLflow
pip install 'deeptab[all]'          # structlog + TensorBoard + MLflow

Note

These backends are loaded lazily. Without the matching extra, DeepTab trains normally and raises only when you enable that specific feature. See the Observability guide for usage.

Hardware Support

DeepTab automatically detects and uses your accelerator, with no configuration needed. It supports NVIDIA GPUs through CUDA and Apple Silicon through the MPS backend, and falls back to the CPU when neither is present.

Inspect what DeepTab can see:

from deeptab import print_hardware_info

print_hardware_info()

DeepTab hardware report
-----------------------
Platform: Darwin (arm64), Python 3.11.8, PyTorch 2.2.0
CPU: 14 logical cores
CUDA: not available
MPS (Apple Silicon): available
Recommended accelerator: mps

The report covers the CPU core count, CUDA GPUs, the Apple Silicon MPS backend, and the accelerator value DeepTab would pick by default.

DeepTab already selects the best available accelerator, so you usually set nothing. For portable scripts you can make this explicit with accelerator="auto", which uses a GPU when present and falls back to the CPU otherwise:

# Uses CUDA or MPS when available, otherwise CPU
model.fit(X_train, y_train, accelerator="auto", max_epochs=100)

Tip

Pin a specific backend ("gpu", "cuda", "mps", or "cpu") only to force one. Unlike "auto", those raise an error if the device is not present.

NVIDIA GPUs (CUDA)

import torch

print(f"CUDA available: {torch.cuda.is_available()}")
print(f"GPU count: {torch.cuda.device_count()}")

Warning

If you have a GPU but CUDA isn’t detected, install PyTorch with CUDA support first:

pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install deeptab

See PyTorch installation guide for your CUDA version.

Multiple GPUs:

export CUDA_VISIBLE_DEVICES=0,1  # Use specific GPUs

Apple Silicon (MPS)

On M-series Macs, DeepTab uses the Metal Performance Shaders (MPS) backend. MPS ships with the standard PyTorch build, so no extra install step is needed.

import torch

print(f"MPS available: {torch.backends.mps.is_available()}")
print(f"MPS built: {torch.backends.mps.is_built()}")

Note

is_available() reports True only on macOS 12.3+ with Apple Silicon and a PyTorch build that includes MPS. When it returns False but is_built() is True, the backend is present but the OS or hardware does not support it, and DeepTab runs on the CPU.

Development Installation

For contributing or using unreleased features:

git clone https://github.com/OpenTabular/DeepTab.git
cd DeepTab
pip install -e .

Note

DeepTab uses Poetry for development. Install with poetry install to get dev tools (pytest, ruff, pyright). See the Contributing guide for details.

Optional: Mamba CUDA Kernels

For 20-30% faster Mamba models, install optimized CUDA kernels:

pip install mamba-ssm

Important

Requirements: NVIDIA GPU (compute capability ≥7.0) | CUDA 11.6+ | C++ compiler

If installation fails, DeepTab automatically falls back to the default implementation. This only affects Mamba-based models.

Quick Troubleshooting

CUDA out of memory? Reduce batch size:

from deeptab.configs import TrainerConfig
model = FTTransformerClassifier(
    trainer_config=TrainerConfig(batch_size=64)
)

Training slow? Check which accelerator DeepTab detected:

from deeptab import print_hardware_info

print_hardware_info()  # "Recommended accelerator" should not be cpu

Module not found? Verify correct environment:

which python
pip list | grep deeptab

Next Steps

Quickstart: Train your first model in 5 minutes
FAQ: Common questions and solutions