Chemprop v2: Message Passing Neural Networks for Molecular Property Prediction

What Chemprop predicts, and who actually needs it

Chemprop is a repository containing message passing neural networks for molecular property prediction. That sentence is the project's own summary, and it is narrower than it sounds. The unit of input is a molecule or a reaction, represented as a graph, and the output is a scalar or vector property learned from labelled examples. The project's topics list names chemistry, drug discovery, machine learning and neural networks, which matches the application list in the README: antibiotic activity against E. coli, a structural class of antibiotics selective against MRSA and vancomycin-resistant enterococci, and 41 ADMET datasets from the Therapeutics Data Commons used to build ADMET-AI. The person who needs this is a computational chemist or ML engineer with a table of molecules and measured properties, who wants a graph neural network rather than a fingerprint plus gradient boosting baseline. If your features are already fixed descriptors and your dataset is small, Chemprop adds a training loop, a GPU dependency and a hyperparameter surface you may not need.

The mechanism: message passing over a molecular graph, plus a reaction mode

The README points to two theory papers for the underlying approach: Analyzing Learned Molecular Representations for Property Prediction for molecules, and Machine Learning of Reaction Properties via Learned Representations of the Condensed Graph of Reaction for reactions. The second title names the mechanism for reaction data directly: a condensed graph of reaction, which is how Chemprop represents a transformation rather than a single species. The README also documents atom and bond level prediction, citing When Do Quantum Mechanical Descriptors Help Graph Neural Networks to Predict Chemical Properties, and an interpretation method based on Multi-Objective Molecule Generation using Interpretable Substructures, available in v2 as an example notebook rather than as a first-class command. One detail worth flagging because it is unusual for a README to volunteer it: the maintainers state a known inconsistency between the published references and the repository, namely that the edge update function in all chemprop versions uses preactivation instead of postactivation initial edge hidden states, with details in the supplementary information of the version 2 paper. If you are reimplementing Chemprop from the papers, that sentence is the difference between matching the code and not.

Version 2 is a rewrite, and the transition guide is a spreadsheet

Chemprop recently underwent a ground-up rewrite and new major release, v2.0.0, according to the README. The migration aid offered is a published spreadsheet described as containing a side-by-side comparison of CLI argument options, a list of which arguments will be implemented in later versions of v2, and a list of changes to default hyperparameters. Read that list of three items carefully. The second one is an admission that some v1 arguments do not exist in v2 yet. The third means that even where an argument survives, its default may have moved, so a v1 config file copied into v2 can train a different model without raising an error. This is the single largest practical risk in the project for existing users, and it is a documentation problem as much as a code problem: the README links the guide but does not reproduce its contents, so you cannot assess your own exposure without opening it. The release cadence visible in the metadata is active, with v2.3.1 in August 2026 following 2.3.0 and v2.2.4 in July 2026, so arguments marked as pending may well have landed since the guide was written. Verify against the current release, not the guide alone.

Getting it running: PyPI, conda-forge, and where the real instructions live

The README carries PyPI and conda-forge version badges, so both distribution channels are published, and the package name in both is chemprop. The README does not inline an install command; it points to the documentation at chemprop.readthedocs.io, and the examples directory in the repository holds tutorial notebooks. That is the honest description of the onboarding path: pip install chemprop or conda install -c conda-forge chemprop gets you the library, and the documentation plus examples/ is where the training invocation, the config keys and the data format are defined. I cannot quote you a training command from this material because the README does not contain one, and inventing one would be worse than saying so. What the README does establish is that a command line interface exists and is argument-driven, since the v1 to v2 transition guide is framed entirely around CLI argument comparison, and that a Python API exists alongside it, since ADMET-AI is described as distributing Chemprop models as a Python package. Plan on reading the Read the Docs site before you write any pipeline code.

Where Chemprop is the wrong tool

Three failure modes are visible from the material itself. First, small datasets: message passing networks learn representations from graph structure, and the published applications are large screening efforts, not ten-compound series. If you have a few dozen measurements, a descriptor-based model will be easier to validate. Second, v1 dependency: if your production pipeline shells out to Chemprop v1 with specific flags, v2 is not a drop-in, and the README's own framing of the transition guide confirms it. The v1 documentation is explicitly described as several versions behind the final v1 release v1.7.1, which means even staying put has a documentation cost. Third, interpretability as a service: the interpretation functionality that existed in v1 is available in v2 as an example notebook, not as a documented command. If your workflow depends on programmatic access to substructure attributions, you are maintaining that notebook yourself. None of these are defects. They are boundaries, and the project states them rather than hiding them.

Alternatives, and the actual difference in approach

The most direct comparison in this material is Chemprop against itself: v1.7.1 versus v2.x. The difference is not accuracy, it is interface. V1 has an args.py file the README calls the best source for documentation on more recently-added features, plus benchmark scripts from the 2023 paper pinned to v1.6.1, an ACS Fall 2023 workshop, a Google Colab notebook, and a nanoHUB tool that requires no installation. V2 has the rewrite, the transition spreadsheet, and example notebooks. If you want the shortest path from zero to a trained model with no local setup, the v1 nanoHUB notebook is documented as requiring no installation, which v2 does not offer. If you want a maintained package with an active release cadence, v2 is the only branch receiving it. Outside Chemprop, the material names ADMET-AI, which is not a competitor but a downstream consumer: it trained Chemprop on 41 TDC datasets and ships the result as a web server and a Python package. That is the pattern to note. Chemprop is a training framework; ADMET-AI is a pre-trained predictor built on it. If your question is what is the ADMET profile of this compound, you want the second thing, not the first.

Licence, citation and the maintenance you are signing up for

The README states Chemprop is free to use under the MIT License, and that the logo is separately licensed under CC0 1.0. The repository metadata reports the licence as NOASSERTION, which is a GitHub classification artifact rather than a contradiction, but if your legal review depends on automated licence detection, expect it to flag this repository and route it to a human. The README asks that you cite the appropriate papers if Chemprop is helpful to your research, listing separate references for version 1, version 2, theory, interpretability, and atom and bond predictions. That is five citation targets, and picking the wrong one is a real possibility for a project that spans two major versions with different papers. The maintenance cost is the version boundary. You are not adopting a library with a stable interface; you are adopting one that has already executed a ground-up rewrite once and documents the breakage in a spreadsheet. Budget for reading release notes on each upgrade, and treat default hyperparameter changes as model changes requiring revalidation, not as patch updates.

Editorial conclusion

Adopt Chemprop v2 if you are starting a molecular property or reaction property modelling project and want a maintained Python package with a documented CLI, a Python API, and a published theory lineage. Stay on v1.7.1 if your pipelines depend on v1 CLI flags, since the maintainers themselves ship a side-by-side argument comparison rather than a drop-in shim. Before committing, open the transition guide linked from the README, check which v1 arguments are listed as not yet implemented in v2, and confirm that your target property type is covered by the v2 examples directory.

Official sources

1. chemprop/chemprop on GitHub
2. Issues
3. Project website
4. README
5. Releases