Skip to content


License: MIT Build Status CodeCov


Element is an extremely lightweight package that defines the elements of the periodic table and allows them to be accessed by symbol, name, atomic number, or mass. It has zero dependencies outside of the Python Standard Library.


Ele is still in early development (0.x releases). The API may change unexpectedly.


Ele only supports a few modes of use. You can retrieve an element from the symbol, the name, the atomic number, or the mass (in amu):

import ele
na = ele.element_from_symbol("Na")
na = ele.element_from_name("sodium")
na = ele.element_from_atomic_number(11)
na = ele.element_from_mass(22.990)

The mass is rounded to a one digit after the decimal before comparison. If you wish to retrieve the element with the mass closest to the specified value you may use the exact=False keyword. In all cases, no matches results in an ElementError.

Ele also offers a function to infer an element from a string with well-defined behavior:

import ele
na = ele.infer_element_from_string("Na")
na = ele.infer_element_from_string("sodium")

infer_element_from_string first checks if the string matches a two-character element symbol. If not, it then checks if the string matches a full element name. The function returns the matching element. If there is no matching element, an ElementError is raised.

Each Element has six attributes which can be accessed (as demonstrated below for na):

import ele
na = ele.element_from_symbol("Na")

The elements can also be accessed by symbol as follows:

import ele
na = ele.Elements.Na


Install is supported through pip:

pip install ele

and conda:

conda install -c conda-forge ele

Complete installation instructions can be found here.

Data Sources

We have compiled the atomic weights in a systematic fashion. Complete details of the data sources are provided here.


Development of Ele was supported by the National Science Foundation under grant NSF Grant Number 1835874. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.