QWE AI Academy End state you’re aiming for: a Python environment where import deepchem as dc works, dc.molnet.load_tox21() pulls a real dataset without an ImportError, and a graph convolutional model fits on GPU. That’s the finish line. Everything below walks backwards from there.
The reason to run DeepChem locally rather than rely on Colab: molecular ML workloads touching large MoleculeNet datasets, custom featurizers, or GPU training don’t fit Colab’s session model. You want reproducibility – pinned RDKit, pinned CUDA, pinned framework. Colab doesn’t give you that.
Pick the right install path (this is where most guides mislead)
Four install paths exist. They are not equivalent:
| Method | What you get | Skip if |
|---|---|---|
pip install deepchem |
Stable 2.8.0, no RDKit, no framework | You plan to run any molnet tutorial |
pip install --pre deepchem |
2.8.1.dev – matches current official tutorials | You need reproducibility over 6+ months |
| Conda + source clone | Full env with soft deps handled by shell script | You’re allergic to conda |
Docker (deepchemio/deepchem) |
Everything preinstalled, GPU-ready | You want to develop against DeepChem itself |
The trap: PyPI’s latest DeepChem release was published April 2, 2024 – stable 2.8.0. But the current docs already target 2.8.1.dev. Install the stable version and half the tutorial notebooks reference APIs you don’t have. The recommended pip command from the official install page is actually pip install --pre deepchem – the --pre flag is not optional if you’re following official tutorials.
That gap between stable and dev is worth sitting with for a moment. Most ML libraries keep their stable docs in sync with their stable release. DeepChem doesn’t, and there’s no warning on the PyPI page. It’s the kind of thing you only discover after 45 minutes of tutorial errors.
System requirements
Python 3.7 through 3.10, per the DeepChem README (as of 2025). Outside that range, you’re on your own.
What actually matters for the workload:
- OS: Linux (Ubuntu 20.04+ is cleanest), macOS Intel, Windows via WSL2
- RAM: 8 GB gets you started; 16 GB once you touch PDBBind or large MoleculeNet sets
- Disk: ~5 GB for the base env – plan for more if you download the full MoleculeNet collection, which covers over 700,000 compounds across 17 datasets spanning quantum mechanics to physiology, per the MoleculeNet paper (Wu et al., 2017)
- GPU: NVIDIA with CUDA 11.8+ is the community baseline for graph conv training below the pain threshold
- Framework backend: one of TensorFlow, PyTorch, or JAX – DeepChem doesn’t bundle any of them
ARM Mac users: as of early 2025, DGL wheels aren’t published for arm64. If your workflow needs graph neural network models that depend on DGL, an M-series Mac will fight you. Either use Rosetta with an x86 conda env, or run inside a Linux Docker container. No clean workaround is documented officially.
Install DeepChem 2.8.0
The conda + pre-release recipe. Longer than pip install deepchem, but it’s the one that doesn’t break on the first molnet call.
# 1. Create isolated env with Python 3.10
conda create -n deepchem python=3.10 -y
conda activate deepchem
# 2. Install RDKit from conda-forge FIRST
conda install -c conda-forge rdkit -y
# 3. Install a framework - pick ONE
pip install tensorflow # or:
# pip install torch torchvision
# pip install jax jaxlib
# 4. Install DeepChem pre-release to match current tutorials
pip install --pre deepchem
# 5. Notebook support (optional)
conda install -c conda-forge nb_conda_kernels matplotlib jupyter -yRDKit first, always. The official docs call it a “soft requirement” – but every molecular featurizer imports it. Docs say soft. Reality: it’s effectively hard for anything useful. And conda-forge’s RDKit is more reliable than rdkit-pypi; the latter causes silent failures that only surface when you run a featurizer, not at install time.
Alternative: Docker (skip everything above)
# CPU
docker pull deepchemio/deepchem:latest
docker run --rm -it deepchemio/deepchem:latest
# GPU (needs nvidia-container-toolkit)
docker run --gpus all --rm -it deepchemio/deepchem:latest:latest rebuilds from master on every commit. Bleeding-edge, but you inherit whatever’s broken today. Pin a version tag – deepchemio/deepchem:2.8.0 – for anything you plan to run more than once.
Verify the install
No config file to edit. Three commands, all three must pass:
python -c "import deepchem as dc; print(dc.__version__)"
# Expected: 2.8.0 (or 2.8.1.dev if you used --pre)
python -c "from rdkit import Chem; print(Chem.MolFromSmiles('CCO'))"
# Expected: <rdkit.Chem.rdchem.Mol object at 0x...>
python -c "import deepchem as dc; tasks, ds, tr = dc.molnet.load_tox21(); print(ds[0].X.shape)"
# Expected: a numpy shape tuple, not an ImportErrorThird command fails with ImportError: This class requires RDKit? Your RDKit is installed in the wrong env – not missing, just invisible to the Python that DeepChem is using.
Useful habit: Add
python -c "import deepchem"to amake verifytarget in your project. Catches environment drift after any dependency update. Takes under a second.
The four errors you’ll actually hit
Pulled from real GitHub issues, not invented.
1. ImportError: This class requires RDKit to be installed
DeepChem imported fine. A featurizer didn’t. This is GitHub issue #4555, confirmed on Colab and still open as of October 2025. Fix: conda install -c conda-forge rdkit in the same environment where DeepChem lives.
2. Terminal imports work, Jupyter doesn’t
Documented in issue #1692. Jupyter is running a different Python. Two fixes: launch Jupyter from inside the deepchem env (conda activate deepchem && jupyter notebook), or install nb_conda_kernels so Jupyter can see all envs.
3. GLIBCXX_3.4.26 not found
libstdc++ mismatch between conda and system. Community-reported on Ubuntu and Colab setups. Fix: conda install -c conda-forge libstdcxx-ng forces conda’s libstdc++ ahead of the system version.
4. zsh: no matches found: deepchem[torch] on macOS
zsh eats the square brackets. Quote them: pip install --pre 'deepchem[torch]'. Buried in the docs. Found by basically everyone who runs macOS.
Upgrade and uninstall
# Upgrade
pip install --pre --upgrade deepchem
# Pin to a specific version
pip install deepchem==2.7.1
# Uninstall Python package only
pip uninstall deepchem -y
# Remove the whole conda env
conda deactivate
conda env remove -n deepchemOne thing worth knowing before upgrading from an older release: the TensorGraph API was removed in a prior major version (community-reported; check the changelog before jumping more than one minor version). If you’re on 2.6.x or earlier, expect some refactoring in your own code.
Docker is the cleanest exit: docker rmi deepchemio/deepchem:latest and the whole install is gone. If you’re evaluating DeepChem rather than committing to it, Docker is the honest answer.
FAQ
Do I have to install RDKit separately?
Yes. Technically a soft dependency – practically, every meaningful featurizer needs it.
Can I use DeepChem without a GPU?
Yes, for a lot of things. Scikit-learn wrappers, random forests, XGBoost, small graph models – all fine on CPU. Where it hurts: 3D featurizations on PDBBind, or training GraphConvModel past a few epochs on any real dataset. The MoleculeNet collection covers over 700,000 compounds across 17 datasets (Wu et al., 2017). CPU training on the full set isn’t a reasonable afternoon project. A few thousand compounds? Fine. The full collection? Get a GPU or use cloud compute.
Is DeepChem the same as MoleculeNet?
No, but installing DeepChem gives you MoleculeNet. It’s a benchmark suite of curated datasets – Tox21, HIV, QM9, and 14 others – built into the library. dc.molnet.load_* is already there. No separate install step, despite what some older tutorials imply.
Next action: run the three verification commands above in a fresh terminal. All three pass? Open The Basic Tools of the Deep Life Sciences and start with the Tox21 example. Anything fails? Check which conda environment is active first. That single check resolves most “it doesn’t work” reports.