DeepCTR-Torch: a PyTorch library of CTR models you can call with fit and predict

The problem: reimplementing every CTR paper from scratch

Click-through-rate prediction has an unusually fragmented literature. DeepFM, xDeepFM, AutoInt, FiBiNET and DCN V2 each introduce a different way of combining sparse categorical features, and each arrives with its own code conventions. If you want to know which one wins on your traffic, the naive path is to read six papers and write six training loops. DeepCTR-Torch exists to remove that work. The README describes it as the PyTorch version of DeepCTR and as an "Easy-to-use, Modular and Extendible package of deep-learning based CTR models", and the model table lists the corresponding papers with links, from the Convolutional Click Prediction Model (CIKM 2015) through PLE (RecSys 2020).

The audience is narrow and specific. This is for people who already have a labeled impression log with categorical fields and want to compare architectures without becoming the maintainer of six codebases. It is not aimed at teams that want a packaged recommender, and it is not a feature store or a training platform. The repository is a library plus a set of example scripts, and the top level entries (deepctr_torch/, docs/, examples/, tests/, setup.py) match that description.

How the models are assembled: layers, inputs, and a Keras-style surface

The design separates feature representation from interaction modeling. The README points to "lots of core components layers which can be used to build your own custom model easily", and the package layout reflects that: deepctr_torch/ holds the models, layers and input handling, while tests/ contains separate tests.models and tests.layers directories, which is what you would expect if layers are meant to be used independently of the shipped models.

The data flow is the standard sparse-feature pipeline. Sparse categorical columns are declared with a vocabulary size and an embedding dimension, dense numeric columns are passed through, and the resulting vectors are fed into the interaction layer that distinguishes one model from another. That is why a single training loop can serve DeepFM, AutoInt and FiBiNET: only the middle section changes. The README states that you can use any complex model with model.fit() and model.predict(), so the outer API is deliberately Keras-like rather than a bespoke trainer.

Multi-task models are included on the same footing. SharedBottom, ESMM, MMOE and PLE appear in the model table, and examples/run_multitask_learning.py exists as a runnable reference. Sequence models are covered too: examples/run_din.py and examples/run_dien.py correspond to Deep Interest Network and Deep Interest Evolution Network, with examples/run_multivalue_movielens.py for multi-value input. The practical consequence is that the hard part of using this library is not the model code, it is shaping your log into the expected column structure.

Installing DeepCTR-Torch and running a first model

The README gives one install command: pip install -U deepctr-torch. The setup.py declares the package name as deepctr-torch, version 0.3.0, with python_requires of >=3.7 and classifiers listing Python 3.7 through 3.13. Dependencies are deliberately small: torch, tqdm and scikit-learn. Note the conditional torch requirement in setup.py, which pins torch>=1.13.0 for Python below 3.8 and torch>=2.4.0 for Python 3.8 and above. On older interpreters you will get an older torch floor, and that is the main reason to check your environment before installing.

bash pip install -U deepctr-torch

After installation, the fastest way to see the library work is to run one of the bundled examples. The repository ships a Criteo sample at examples/criteo_sample.txt and a classification script at examples/run_classification_criteo.py. Running the script trains a model against that small file, so it is a smoke test for the install rather than a benchmark. The other samples follow the same pattern: examples/byterec_sample.txt and examples/movielens_sample.txt back the DIN, DIEN, multi-value and regression scripts.

bash python examples/run_classification_criteo.py

The example scripts are the closest thing to a tutorial inside the repository. For the narrative version, the README links to a Quick Start page on the Read the Docs site and to a separate Chinese introduction article. If you want to adapt the example to your own data, the work is in declaring your sparse and dense columns correctly; the README does not document a schema auto-detection path, so expect to write that mapping yourself.

Where DeepCTR-Torch stops: no serving layer, no rollback story

The README documents training and prediction calls, and nothing beyond them. There is no mention of an HTTP server, a batch scoring job, a model registry, or a serialization format for deployment. If your goal is a low-latency prediction service, this library gives you the model object and leaves the rest to you. That is a real boundary, not a missing checkbox: a CTR model in production needs feature encoding that matches training exactly, and nothing in the repository guarantees that the training-time column mapping survives into a serving path.

The second limitation is version drift. The gap between release v0.2.9 (2022-10-21) and v0.3.0 (2026-04-18) spans several years, and the last push to the repository was on 2026-07-09. A jump of that size in a library that pins torch>=2.4.0 for modern Python means you should read the release notes before upgrading rather than assuming drop-in compatibility with a 0.2.x training script.

The third limitation is scale. The examples use small sample files, and the README does not describe distributed training, sharded embedding tables, or parameter-server support. If your embedding tables do not fit on one device, this is the wrong tool, and the absence of any distributed story in the documentation is the signal.

How it differs from TorchRec and FuxiCTR

The related searches around this project include TorchRec and FuxiCTR, and the contrast is instructive. TorchRec is Meta's PyTorch library for large-scale recommendation, built around sharded embedding tables and distributed training. DeepCTR-Torch takes the opposite position: it targets single-process training of published model architectures, and its dependency list (torch, tqdm, scikit-learn) reflects that. If your problem is fitting a model on one machine, DeepCTR-Torch is the shorter path. If your problem is fitting embeddings that do not fit on one machine, TorchRec addresses a layer of the stack that DeepCTR-Torch does not touch.

FuxiCTR is the closer comparison, because it also collects CTR architectures behind a common training interface. The difference in emphasis is the model inventory and the surrounding ecosystem. DeepCTR-Torch inherits its model list from DeepCTR and pairs it with a Chinese-language discussion community linked from the README. Which one to pick depends on which paper set you care about and which codebase you can read comfortably; both are attempts to solve the same fragmentation problem.

Licence and the cost of staying current

The project is licensed under Apache-2.0, and setup.py carries the matching classifier, License :: OSI Approved :: Apache Software License. For most teams that means you can use it commercially and modify it, subject to the usual Apache-2.0 conditions around notices and attribution. This is not legal advice; if you are redistributing modified source or embedding it in a product, have your own counsel read the LICENSE file at the repository root.

The upgrade cost is the more practical concern. With a release cadence that produced v0.2.8 in 2022-06-19, v0.2.9 in 2022-10-21 and then v0.3.0 in 2026-04-18, you should treat upgrades as infrequent but potentially large. Pin the version in your requirements, keep the example scripts in your test suite so a torch bump fails loudly, and read the release notes for v0.3.0 before moving off 0.2.x. The README does not document a deprecation policy, so there is no published promise about how long old APIs will survive.

Editorial conclusion

Adopt DeepCTR-Torch if you are an applied researcher or a small team that needs to compare published CTR architectures on your own data without rewriting each paper. Skip it if you need a trained model behind an HTTP endpoint, since the repository contains no serving component and the documentation does not describe deployment. Before committing, verify that pip install deepctr-torch pulls a torch version compatible with your CUDA build, and check that the example scripts under examples/ run against your own column layout rather than the bundled Criteo and MovieLens samples.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. shenweichen/DeepCTR-Torch on GitHub