Skip to main content

Combine tabular data with text and images using Wide and Deep models in Pytorch

Project description

PyPI version Python 3.7 3.8 3.9 Build Status Documentation Status codecov Code style: black Maintenance contributions welcome Slack


A flexible package to use Deep Learning with tabular data, text and images using wide and deep models.


Companion posts and tutorials: infinitoml

Experiments and comparisson with LightGBM: TabularDL vs LightGBM

Slack: if you want to contribute or just want to chat with us, join slack


pytorch-widedeep is based on Google's Wide and Deep Algorithm

In general terms, pytorch-widedeep is a package to use deep learning with tabular data. In particular, is intended to facilitate the combination of text and images with corresponding tabular data using wide and deep models. With that in mind there are a number of architectures that can be implemented with just a few lines of code. For details on the main components of those architectures please visit the repo.


Install using pip:

pip install pytorch-widedeep

Or install directly from github

pip install git+

Developer Install

# Clone the repository
git clone
cd pytorch-widedeep

# Install in dev mode
pip install -e .

Important note for Mac users: at the time of writing the latest torch release is 1.9. Some past issues when running on Mac, present in previous versions, persist on this release and the data-loaders will not run in parallel. In addition, since python 3.8, the multiprocessing library start method changed from 'fork' to'spawn'. This also affects the data-loaders (for any torch version) and they will not run in parallel. Therefore, for Mac users I recommend using python 3.7 and torch <= 1.6 (with the corresponding, consistent version of torchvision, e.g. 0.7.0 for torch 1.6). I do not want to force this versioning in the file since I expect that all these issues are fixed in the future. Therefore, after installing pytorch-widedeep via pip or directly from github, downgrade torch and torchvision manually:

pip install pytorch-widedeep
pip install torch==1.6.0 torchvision==0.7.0

None of these issues affect Linux users.

Quick start

Binary classification with the adult dataset using Wide and DeepDense and defaults settings.

Building a wide (linear) and deep model with pytorch-widedeep:

import pandas as pd
import numpy as np
import torch
from sklearn.model_selection import train_test_split

from pytorch_widedeep import Trainer
from pytorch_widedeep.preprocessing import WidePreprocessor, TabPreprocessor
from pytorch_widedeep.models import Wide, TabMlp, WideDeep
from pytorch_widedeep.metrics import Accuracy

# the following 4 lines are not directly related to ``pytorch-widedeep``. I
# assume you have downloaded the dataset and place it in a dir called
# data/adult/
df = pd.read_csv("data/adult/")
df["income_label"] = (df["income"].apply(lambda x: ">50K" in x)).astype(int)
df.drop("income", axis=1, inplace=True)
df_train, df_test = train_test_split(df, test_size=0.2, stratify=df.income_label)

# prepare wide, crossed, embedding and continuous columns
wide_cols = [
cross_cols = [("education", "occupation"), ("native-country", "occupation")]
embed_cols = [
    ("education", 16),
    ("workclass", 16),
    ("occupation", 16),
    ("native-country", 32),
cont_cols = ["age", "hours-per-week"]
target_col = "income_label"

# target
target = df_train[target_col].values

# wide
wide_preprocessor = WidePreprocessor(wide_cols=wide_cols, crossed_cols=cross_cols)
X_wide = wide_preprocessor.fit_transform(df_train)
wide = Wide(wide_dim=np.unique(X_wide).shape[0], pred_dim=1)

# deeptabular
tab_preprocessor = TabPreprocessor(embed_cols=embed_cols, continuous_cols=cont_cols)
X_tab = tab_preprocessor.fit_transform(df_train)
deeptabular = TabMlp(
    mlp_hidden_dims=[64, 32],

# wide and deep
model = WideDeep(wide=wide, deeptabular=deeptabular)

# train the model
trainer = Trainer(model, objective="binary", metrics=[Accuracy])

# predict
X_wide_te = wide_preprocessor.transform(df_test)
X_tab_te = tab_preprocessor.transform(df_test)
preds = trainer.predict(X_wide=X_wide_te, X_tab=X_tab_te)

# Save and load

# Option 1: this will also save training history and lr history if the
# LRHistory callback is used"model_weights", save_state_dict=True)

# Option 2: save as any other torch model, "model_weights/")

# From here in advance, Option 1 or 2 are the same. I assume the user has
# prepared the data and defined the new model components:
# 1. Build the model
model_new = WideDeep(wide=wide, deeptabular=deeptabular)

# 2. Instantiate the trainer
trainer_new = Trainer(

# 3. Either start the fit or directly predict
preds = trainer_new.predict(X_wide=X_wide, X_tab=X_tab)

Of course, one can do much more. See the Examples folder, the documentation or the companion posts for a better understanding of the content of the package and its functionalities.


pytest tests


This library takes from a series of other libraries, so I think it is just fair to mention them here in the README (specific mentions are also included in the code).

The Callbacks and Initializers structure and code is inspired by the torchsample library, which in itself partially inspired by Keras.

The TextProcessor class in this library uses the fastai's Tokenizer and Vocab. The code at utils.fastai_transforms is a minor adaptation of their code so it functions within this library. To my experience their Tokenizer is the best in class.

The ImageProcessor class in this library uses code from the fantastic Deep Learning for Computer Vision (DL4CV) book by Adrian Rosebrock.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pytorch-widedeep, version 1.0.10
Filename, size File type Python version Upload date Hashes
Filename, size pytorch_widedeep-1.0.10-py3-none-any.whl (149.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pytorch-widedeep-1.0.10.tar.gz (106.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page