padelpy2

padelpy2 is a Python bridge to the stock PaDEL-Descriptor Java application (Yap, 2011). It provides an RDKit-native Calculator with pandas DataFrame results, typed descriptor/fingerprint catalogs, and a low-level padeldescriptor CLI surface compatible with padelpy.

Documentation: API and guides · When to use which package

When to use

Need	Prefer
Minimal env; SMILES/SDF → dicts; no RDKit/pandas	padelpy
Stock Yap JAR; file/padeldescriptor only (no RDKit/pandas)	padelpy2 (default install)
Stock Yap JAR + RDKit → DataFrame Calculator	padelpy2 with [calc]
General descriptors without PaDEL identity	mordredcommunity or RDKit

See the when-to-use guide for stock-JAR fidelity notes.

Features

• Stock Yap PaDEL-Descriptor JAR (same family as padelpy)
• RDKit Mol → pandas DataFrame via Calculator
• Typed 2D/3D descriptor and fingerprint catalogs; custom subsets
• PaDELConfig for PaDEL CLI-aligned options (threads, aromaticity, salts, …)
• Low-level padeldescriptor for file-based / padelpy-style workflows
• Regression oracles pinning stock-JAR column schemas and values

---

Installation

Minimal (low-level padeldescriptor)

pip install padelpy2

Requires Python 3.9+ and a system Java JRE 8+ on PATH. No pandas or RDKit.

Calculator / DataFrame workflows

pip install "padelpy2[calc]"   # pandas + RDKit

Or conda-forge RDKit plus the pandas extra:

conda install -c conda-forge rdkit
pip install "padelpy2[pandas]"

Stock-JAR oracle tests expect RDKit 2026.03.x (or regenerating fixtures after an intentional RDKit bump).

From Source

git clone https://github.com/cognitive-chemistry-labs/padelpy2
cd padelpy2
pip install -e ".[calc]"   # or bare pip install -e . for padeldescriptor only

Requirements:

• Python 3.9–3.13
• Java Runtime Environment (JRE) 8 or higher on PATH (padelpy2 does not auto-download a JRE)
• Optional: pandas + RDKit for Calculator / compat / qc (padelpy2[calc])

---

Quick Start

from rdkit import Chem
from padelpy2 import Calculator, descriptors

# Example molecules (SMILES)
smiles = [
    "CN=C=O",
    "CC(=O)NCCC1=CNc2c1cc(OC)cc2",
    "OCCc1c(C)[n+](cs1)Cc2cnc(C)nc2N",
]
mols = [Chem.AddHs(Chem.MolFromSmiles(smi)) for smi in smiles]

# Calculate all available descriptors
calc = Calculator(descriptors)
results = calc(mols)
print(results)

---

Usage Examples

Calculate 2D Descriptors Only

from padelpy2 import Calculator, descriptors_2d
calc = Calculator(descriptors_2d)
results = calc(mols)

Calculate 3D Descriptors Only

from padelpy2 import Calculator, descriptors_3d
calc = Calculator(descriptors_3d)
results = calc(mols)

Calculate Fingerprints

from padelpy2 import Calculator, fingerprints
calc = Calculator(fingerprints)
results = calc(mols)

Calculate Specific Descriptors

from padelpy2.descriptors import Weight, XLogP
calc = Calculator([Weight, XLogP])
results = calc(mols)

Calculate a Specific Fingerprint

from padelpy2.fingerprints import MACCSFingerprinter
calc = Calculator([MACCSFingerprinter])
results = calc(mols)

---

API Overview

Calculator

The main interface for descriptor/fingerprint calculation.

Calculator(descriptors: Iterable[Descriptor or Fingerprint], config: PaDELConfig = None)

• descriptors: List of descriptor/fingerprint objects (see below)
• config: Optional configuration (threads, 3D conversion, etc.)

Call

results = calc(mols)

• mols: List of RDKit Mol objects
• Returns: pandas DataFrame (engine Name column dropped by default)

Descriptor and Fingerprint Sets

• descriptors: All available descriptors (2D and 3D)
• descriptors_2d: Only 2D descriptors
• descriptors_3d: Only 3D descriptors
• fingerprints: All available fingerprints

Custom Configuration

from padelpy2 import PaDELConfig
config = PaDELConfig(threads=4, convert3d=True)
calc = Calculator(descriptors, config=config)

---

Low-Level Wrapper Usage

For advanced use cases, you can call the low-level PaDEL-Descriptor wrapper directly. This allows you to execute the underlying Java tool with custom arguments and file-based workflows. The keyword surface is aligned with padelpy for migration continuity.

Example: Using the padeldescriptor Function

from padelpy2.wrapper import padeldescriptor

# Calculate 2D descriptors for a directory of structure files (e.g., SDF or MOL)
output_csv = padeldescriptor(
    d_2d=True,
    mol_dir="/path/to/structures/",  # directory or file with molecules
    d_file="/path/to/output.csv",    # output CSV file
    threads=4,                       # number of threads
    headless=True                    # run in headless mode (no GUI)
)
print(f"Results written to: {output_csv}")

Key Parameters

• mol_dir: Path to a directory or file containing molecular structures (SDF, MOL, etc.)
• d_file: Output file for descriptors (CSV)
• d_2d, d_3d, fingerprints: Enable calculation of 2D, 3D descriptors, or fingerprints
• threads: Number of threads to use
• config, descriptortypes: Optional config or descriptor type files
• convert3d, removesalt, retainorder, etc.: Advanced options (see docstring in padelpy2/wrapper.py)
• use_tempfile: If True and d_file is not set, a temporary file is used for output

Returns the path to the output file, or raises an error if the calculation fails.

See the function docstring in padelpy2/wrapper.py for a full list of options and details.

---

Links

• PaDEL-Descriptor Homepage
• Project Repository
• Documentation
• When to use
• Migrating from padelpy
• Changelog
• Contributing
• Security

---

Examples

• RDKit Calculator tutorial: examples/example.ipynb
• Low-level padeldescriptor (no RDKit/pandas): examples/padeldescriptor_lowlevel.ipynb
• Docs: Examples