molmass 2026.1.8

Molecular mass calculations

Molmass is a Python library, console script, and web application to calculate the molecular mass (average, nominal, and isotopic pure), the elemental composition, and the mass distribution spectrum of a molecule given by its chemical formula, relative element weights, or sequence.

Calculations are based on the isotopic composition of the elements. Mass deficiency due to chemical bonding is not taken into account.

The library includes a database of physicochemical and descriptive properties of the chemical elements.

Author:

Christoph Gohlke

License:

BSD-3-Clause

Version:

2026.1.8

DOI:

10.5281/zenodo.7135495

Quickstart

Install the molmass package and all dependencies from the Python Package Index:

python -m pip install -U "molmass[all]"

Print the console script usage:

python -m molmass --help

Run the web application:

python -m molmass --web

The molmass library is documented via docstrings.

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements

This revision was tested with the following requirements and dependencies (other versions may work):

• CPython 3.11.9, 3.12.10, 3.13.11, 3.14.2

• Flask 3.1.2 (optional)

• Pandas 2.3.3 (optional)

• wxPython 4.2.4 (optional)

Revisions

2026.1.8

• Improve code quality.

2025.12.12

• Make boolean arguments keyword-only (breaking).

2025.11.11

• Allow empty formulas (breaking).

• Derive FormulaError from ValueError.

• Move tests to separate test module.

2025.9.4

• Precompile regex patterns.

• Remove doctest command line option.

• Drop support for Python 3.10, support Python 3.14.

2025.4.14

• Add mass_charge_ratio helper function (#17).

• Drop support for Python 3.9.

2024.10.25

• …

Refer to the CHANGES file for older revisions.

Examples

Calculate the molecular mass, elemental composition, and mass distribution of a molecule from its chemical formula:

>>> from molmass import Formula
>>> f = Formula('C8H10N4O2')  # Caffeine
>>> f
Formula('C8H10N4O2')
>>> f.formula  # hill notation
'C8H10N4O2'
>>> f.empirical
'C4H5N2O'
>>> f.mass  # average mass
194.1909...
>>> f.nominal_mass  # == f.isotope.massnumber
194
>>> f.monoisotopic_mass  # == f.isotope.mass
194.0803...
>>> f.atoms
24
>>> f.charge
0
>>> f.composition().dataframe()
         Count  Relative mass  Fraction
Element...
C            8      96.085920  0.494801
H           10      10.079410  0.051905
N            4      56.026812  0.288514
O            2      31.998810  0.164780
>>> f.spectrum(min_intensity=0.01).dataframe()
             Relative mass  Fraction  Intensity %         m/z
Mass number...
194             194.080376  0.898828   100.000000  194.080376
195             195.082873  0.092625    10.305100  195.082873
196             196.084968  0.008022     0.892492  196.084968
197             197.087214  0.000500     0.055681  197.087214

Access physicochemical and descriptive properties of the chemical elements:

>>> from molmass import ELEMENTS, Element
>>> e = ELEMENTS['C']
>>> e
Element(
    6, 'C', 'Carbon',
    group=14, period=2, block='p', series=1,
    mass=12.01074, eleneg=2.55, eleaffin=1.262118,
    covrad=0.77, atmrad=0.91, vdwrad=1.7,
    tboil=5100.0, tmelt=3825.0, density=3.51,
    eleconfig='[He] 2s2 2p2',
    oxistates='4*, 2, -4*',
    ionenergy=(
        11.2603, 24.383, 47.877, 64.492, 392.077,
        489.981,
    ),
    isotopes={
        12: Isotope(12.0, 0.9893, 12),
        13: Isotope(13.00335483507, 0.0107, 13),
    },
)
>>> e.number
6
>>> e.symbol
'C'
>>> e.name
'Carbon'
>>> e.description
'Carbon is a member of group 14 of the periodic table...'
>>> e.eleconfig
'[He] 2s2 2p2'
>>> e.eleconfig_dict
{(1, 's'): 2, (2, 's'): 2, (2, 'p'): 2}
>>> str(ELEMENTS[6])
'Carbon'
>>> len(ELEMENTS)
109
>>> sum(e.mass for e in ELEMENTS)
14693.181589001...
>>> for e in ELEMENTS:
...     e.validate()
...