RDKit for Python (PyPI)

2026.03.01 · active · verified Fri Apr 17

RDKit is a collection of chemoinformatics and machine-learning software written in C++ and Python. The `rdkit-pypi` package provides pre-built wheels for the RDKit library, enabling easy installation via pip on various platforms and Python versions. This addresses common build issues encountered with the upstream RDKit PyPI package, which often only provides source distributions. It follows a rapid release cadence, syncing with RDKit's development.

Common errors

```
ImportError: No module named 'rdkit'
```
cause The `rdkit` library (or `rdkit-pypi`) is not installed in the current Python environment, or a previous `pip install rdkit` attempt failed to build the package.

fix Ensure `rdkit-pypi` is correctly installed: `pip install rdkit-pypi`. Verify your Python environment is active where it was installed.
```
[CRITICAL] RDKit Error: C++ exception: Bad SMILES
```
cause An attempt was made to create a molecule from an invalid or malformed SMILES string.

fix Validate your input SMILES strings before passing them to functions like `Chem.MolFromSmiles()`. Use a `try-except` block to gracefully handle potential parsing errors or check for `None` return values: `mol = Chem.MolFromSmiles(smiles_string); if mol is None: print('Invalid SMILES')`.
```
AttributeError: module 'rdkit.Chem.Draw' has no attribute 'MolsToGridImage'
```
cause The specific function `MolsToGridImage` or other drawing utilities are not found. This might be due to an older RDKit version or an incorrect import path.

fix Ensure you are importing from the correct submodule, typically `rdkit.Chem.Draw`. For older RDKit versions, some drawing functions might have been in `rdkit.Chem` directly or have different names. Upgrade `rdkit-pypi` to the latest version: `pip install --upgrade rdkit-pypi`.

Warnings

gotcha Many users incorrectly attempt to install the upstream `rdkit` package directly via `pip install rdkit`. The official `rdkit` package on PyPI typically only provides source distributions, leading to build errors without specific C++ dependencies and compilers. The `rdkit-pypi` package provides pre-built wheels, making `pip install rdkit-pypi` the recommended method for pip users.
Fix: Always use `pip install rdkit-pypi` for easy installation with pre-built wheels.
gotcha Mixing RDKit installations (e.g., `conda install rdkit` and `pip install rdkit-pypi`) in the same Python environment can lead to linker errors, module conflicts, or unexpected behavior due to different underlying C++ libraries.
Fix: Use a dedicated virtual environment and stick to a single installation method (either `conda` or `pip install rdkit-pypi`).
breaking The RDKit API can evolve between major releases, leading to deprecations or changes in function signatures, class constructors, or module locations. `rdkit-pypi` versions closely track RDKit releases, so these changes apply.
Fix: Consult the official RDKit release notes and migration guides when upgrading across major RDKit versions. Test your code thoroughly after upgrades.
gotcha Processing very large molecules, extensive conformer generation, or high-throughput calculations/drawing without proper memory management can lead to significant memory consumption and potential `MemoryError` or `Segmentation fault` crashes.
Fix: Optimize your code for memory efficiency, process data in batches, and ensure your system has sufficient RAM for computationally intensive tasks. Consider using RDKit's C++ API for extreme cases or distributed computing.

Install

pip install rdkit-pypi Install RDKit pre-built wheels

Imports

Chem
```
from rdkit import Chem
```
AllChem
```
from rdkit.Chem import AllChem
```
DataStructs
```
from rdkit import DataStructs
```

MolsToGridImage

wrong:

from rdkit.Chem import MolsToGridImage

correct:

from rdkit.Chem.Draw import MolsToGridImage

Drawing utilities are typically in rdkit.Chem.Draw

IPythonConsole
```
from rdkit.Chem.Draw import IPythonConsole
```
Required to render molecules directly in Jupyter notebooks; often imported for side effects.

Quickstart

This example demonstrates how to create RDKit molecule objects from SMILES strings, convert them back to SMILES, and visualize them as a grid image. Ensure you have matplotlib and pillow installed for image generation.

from rdkit import Chem
from rdkit.Chem.Draw import MolsToGridImage

# Create a molecule from SMILES string
mol1 = Chem.MolFromSmiles('CCO')
mol2 = Chem.MolFromSmiles('c1ccccc1')

print(f"SMILES for ethanol: {Chem.MolToSmiles(mol1)}")
print(f"SMILES for benzene: {Chem.MolToSmiles(mol2)}")

# Generate an image grid (requires matplotlib and pillow, often pre-installed)
img = MolsToGridImage([mol1, mol2], molsPerRow=2, subImgSize=(200, 200))
# In a Jupyter environment, img would display directly
# If not in Jupyter, you might save it: img.save('molecules.png')

view raw JSON →