padelpy2

July 27, 2026 · View on GitHub

CogniChem Logo

padelpy2

GitHub version PyPI version GitHub license

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

NeedPrefer
Minimal env; SMILES/SDF → dicts; no RDKit/pandaspadelpy
Stock Yap JAR; file/padeldescriptor only (no RDKit/pandas)padelpy2 (default install)
Stock Yap JAR + RDKit → DataFrame Calculatorpadelpy2 with [calc]
General descriptors without PaDEL identitymordredcommunity 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.

Examples