{"id":28401,"library":"torchrec","title":"TorchRec","description":"TorchRec is a PyTorch library for building and scaling recommendation systems, providing modular building blocks for distributed training, large embeddings, and advanced sharding strategies. Current version is 1.6.0, with a release cadence of roughly quarterly.","status":"active","version":"1.6.0","language":"python","source_language":"en","source_url":"https://github.com/meta-pytorch/torchrec","tags":["recommendation-systems","pytorch","embeddings","distributed-training","deep-learning"],"install":[{"cmd":"pip install torchrec","lang":"bash","label":"PyPI installation"},{"cmd":"pip install torchrec --prefer-binary","lang":"bash","label":"Install with pre-built binaries"}],"dependencies":[{"reason":"Core PyTorch dependency","package":"torch","optional":false},{"reason":"Required for GPU embedding operations","package":"fbgemm-gpu","optional":true}],"imports":[{"note":"EmbeddingBagCollection is in top-level torchrec, not in a submodule.","wrong":"from torchrec.models import EmbeddingBagCollection","symbol":"EmbeddingBagCollection","correct":"from torchrec import EmbeddingBagCollection"},{"note":"KeyedJaggedTensor is exported from torchrec; no need to import from submodules.","wrong":"from torchrec.sparse import KeyedJaggedTensor","symbol":"KeyedJaggedTensor","correct":"from torchrec import KeyedJaggedTensor"},{"note":"DenseArch is in the deepfm model submodule, not directly in torchrec.","wrong":"from torchrec import DenseArch","symbol":"DenseArch","correct":"from torchrec.models.deepfm import DenseArch"}],"quickstart":{"code":"import torch\nfrom torchrec import EmbeddingBagCollection, KeyedJaggedTensor\n\n# Create an embedding bag collection with 2 tables\nebc = EmbeddingBagCollection(\n    tables=[\n        {\"name\": \"users\", \"num_embeddings\": 1000, \"embedding_dim\": 64},\n        {\"name\": \"items\", \"num_embeddings\": 5000, \"embedding_dim\": 128},\n    ],\n    device=torch.device(\"cpu\"),\n)\n\n# Dummy sparse features\nfeatures = KeyedJaggedTensor(\n    keys=[\"users\", \"items\"],\n    values=torch.tensor([1, 2, 3, 4, 5]),\n    lengths=torch.tensor([2, 0, 1, 0, 2]),\n    offsets=torch.tensor([0, 2, 2, 3, 3, 5]),\n)\n\n# Forward pass\noutput = ebc(features)\nprint(output)\n","lang":"python","description":"Minimal example using EmbeddingBagCollection and KeyedJaggedTensor on CPU."},"warnings":[{"fix":"git remote set-url origin https://github.com/meta-pytorch/torchrec.git","message":"In v1.4.0, the GitHub repository moved from pytorch/torchrec to meta-pytorch/torchrec. Update your git remotes and any references to the old organization.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Migrate any custom type checking configuration to Pyrefly; refer to https://github.com/facebook/pyrefly","message":"Starting with v1.5.0, type checking migrated from Pyre to Pyrefly. All deprecated Pyre1 configurations have been removed in v1.6.0.","severity":"deprecated","affected_versions":">=1.5.0"},{"fix":"Ensure torch.__version__ >= '2.0.0' and CUDA >= 11.7. Check compatibility with the torchrec version you install.","message":"TorchRec requires PyTorch version >=2.0.0 and CUDA (if using GPU) 11.7+. Using older PyTorch or CUDA versions can cause silent runtime errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin torchrec==1.5.0 or similar exact version in your requirements.txt.","message":"The module 'torchrec.distributed' has frequent API changes. If you use distributed training, pin your torchrec version to avoid breakage.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Install fbgemm-gpu from the appropriate source: pip install fbgemm-gpu --prefer-binary (if available for your CUDA version).","cause":"TorchRec depends on fbgemm-gpu for GPU operations, which is not installed automatically.","error":"ModuleNotFoundError: No module named 'fbgemm'"},{"fix":"Ensure all inputs and the embedding module are moved to the same device using .to(device).","cause":"Mixing CPU and GPU tensors in KeyedJaggedTensor or embedding modules.","error":"RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!"},{"fix":"Use positional arguments: KeyedJaggedTensor(keys, values, lengths, offsets) or upgrade torchrec.","cause":"Using older constructor pattern for KeyedJaggedTensor; the API changed.","error":"TypeError: keyed_jagged_tensor() got an unexpected keyword argument 'keys'"},{"fix":"Use: from torchrec.models.deepfm import DenseArch","cause":"DenseArch is not exported from torchrec top-level; it's in torchrec.models.deepfm.","error":"ImportError: cannot import name 'DenseArch' from 'torchrec'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}