Install & Compatibility
Where this runs
tested against v2026.3.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.9s · import 0.134s · 252MB
252MB installed
● package 252MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chem
✓ from rdkit import Chem
The primary module for molecular manipulation, reading/writing, and properties.
AllChem
✓ from rdkit.Chem import AllChem
✗ from rdkit import AllChem
Contains more advanced or less frequently used functionality (e.g., 2D->3D generation, force fields). Importing from `rdkit.Chem` is correct; a direct `from rdkit import AllChem` is incorrect.
Draw
✓ from rdkit.Chem import Draw
Module for molecular visualization and drawing.
DataStructs
✓ from rdkit import DataStructs
Used for working with molecular fingerprints and similarity calculations.
This quickstart demonstrates how to create a molecule object from a SMILES string, retrieve basic properties like atom counts, and highlights the importance of adding explicit hydrogens for certain applications. It also shows how to visualize the molecule using `rdkit.Chem.Draw`.
from rdkit import Chem
from rdkit.Chem import Draw
# Create a molecule from a SMILES string
smiles_string = "CCO"
molecule = Chem.MolFromSmiles(smiles_string)
if molecule is not None:
print(f"Successfully created molecule from SMILES: {smiles_string}")
print(f"Number of heavy atoms: {molecule.GetNumHeavyAtoms()}")
# Optionally add hydrogens for better geometry or calculations
mol_with_hs = Chem.AddHs(molecule)
print(f"Total number of atoms (including Hs): {mol_with_hs.GetNumAtoms()}")
# Visualize the molecule (requires Pillow installed)
# img = Draw.MolToImage(molecule)
# img.show() # Uncomment to display image
else:
print(f"Failed to create molecule from SMILES: {smiles_string}")
print("This might happen for invalid SMILES strings or if sanitization fails.")
Debug
Known issues
breakingThe PyPI package name for RDKit changed from `rdkit-pypi` to `rdkit`. Older installations or `requirements.txt` files might still refer to `rdkit-pypi`.fixUpdate your `pip install` commands and `requirements.txt` to use `pip install rdkit`.
affects: <=2022.09.5 (for `rdkit-pypi`), all current versions (for new `rdkit` package)
gotchaMolFromSmiles (and similar functions) return `None` on failure (e.g., for invalid SMILES strings or during sanitization issues) instead of raising an exception. Directly attempting to use methods on a `None` object will lead to `AttributeError`.fixAlways check if the returned molecule object is `None` before proceeding: `mol = Chem.MolFromSmiles(smi); if mol is not None: ...`
affects: All versions
gotchaRDKit molecules often implicitly handle hydrogens. For accurate structural calculations, 3D conformer generation, or correct atom counts, explicit hydrogens often need to be added.fixUse `mol = Chem.AddHs(mol)` to add explicit hydrogens after creating a molecule. They can be removed later with `Chem.RemoveHs(mol)` if needed.
affects: All versions
breakingMajor releases may introduce backwards incompatible changes, particularly in stereochemistry perception, MCS (Maximum Common Substructure) algorithms, canonicalization, ring finding, and default conformer generation parameters (e.g., ETKDG). These changes, while improving accuracy, can lead to different results or require code adjustments.fixReview the detailed release notes for specific versions when upgrading, especially for applications sensitive to molecular representations or calculated properties. Pin RDKit versions for reproducibility in production or research.
affects: >=2023.03, >=2023.09, >=2025.09.1
gotchaMolecule sanitization is a critical step, and `Chem.SanitizeMol()` can raise `KekulizeException` or `ValenceException` for chemically invalid structures, particularly with problematic nitrogen protonation or incorrect valences. This can halt processing or result in `None` molecules if not handled.fixEncapsulate molecule creation and sanitization in `try-except` blocks, or implement robust filtering. Understand common issues like pyrrolic vs. pyridinic nitrogens which often cause sanitization failures.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'rdkit'
The RDKit library is not installed or not accessible within the current Python environment.
fixUse `conda install -c rdkit rdkit` (recommended for RDKit) or `pip install rdkit-pypi` to install the library.
NameError: name 'MolFromSmiles' is not defined
Common RDKit functions like `MolFromSmiles` are part of the `rdkit.Chem` module and must be explicitly imported or called via `Chem`.
fixFirst import `Chem` using `from rdkit import Chem`, then call the function as `mol = Chem.MolFromSmiles("CCO")`. AttributeError: module 'rdkit.Chem' has no attribute 'AllChem'
The `AllChem` submodule, which provides extended chemical functionalities, is not directly an attribute of `rdkit.Chem` and must be imported separately.
fixImport `AllChem` explicitly using `from rdkit.Chem import AllChem`.
ValueError: Sanitization error: [...]
RDKit's default sanitization process failed because the input SMILES string represents an invalid or unstable chemical structure.
fixValidate the input SMILES string for chemical correctness, or bypass sanitization with `Chem.MolFromSmiles("invalid_smiles", sanitize=False)` (use with caution). Upgrade
Version history
2026.3.5latest on PyPI · released Aug 3, 2026
Audit
Dependencies
numpyoptionalCommonly required for numerical operations and data handling, often implicitly pulled by RDKit functionalities.
PillowoptionalRequired for image generation and visualization features like `rdkit.Chem.Draw.MolToImage()`.