Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.296s · 20.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.278s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Particle
✓ from particle import Particle
Main class for interacting with PDG particle data.
PDGID
✓ from particle import PDGID
Class for querying properties of PDG identification numbers.
pdgid.literals
✓ import particle.pdgid.literals as pdgid_literals
Provides aliases for PDGID instances, e.g., `pdgid_literals.pi_plus`.
literals
✓ import particle.literals as particle_literals
Provides aliases for Particle instances, e.g., `particle_literals.phi_1020`.
This quickstart demonstrates how to create `PDGID` and `Particle` objects, access their properties, and perform searches for particles based on specific criteria. It also shows the integration with `hepunits` for handling physical units.
from particle import PDGID, Particle
from hepunits import GeV
# Working with PDG IDs
pid_pion = PDGID(211)
print(f"PDGID 211 is a meson: {pid_pion.is_meson}")
# Getting a Particle object from its PDG ID
pion = Particle.from_pdgid(211)
print(f"Pion mass: {pion.mass / GeV:.3f} GeV")
# Searching for particles by properties
neutral_beauty_hadrons = Particle.findall(lambda p: p.charge == 0 and p.has_bottom and p.mass > 5.2 * GeV and p.mass < 5.3 * GeV)
for p in neutral_beauty_hadrons:
print(f"Found neutral beauty hadron: {p.name} (mass={p.mass / GeV:.3f} GeV)")
particle --version
Debug
Known issues
breakingPython 3.7 and 3.8 support has been dropped in recent versions. Python 3.7 support was removed in v0.24.0, and Python 3.8 support was removed in v0.26.0.fixUpgrade your Python environment to 3.9 or higher. The current version (0.26.1) requires Python >=3.9.
affects: >=0.24.0
breakingDeprecated methods were removed in version 0.24.0 of the library.fixConsult the changelog or documentation for version 0.24.0 to identify and update any calls to removed methods.
affects: >=0.24.0
gotchaThe default PDG data table is updated annually with new releases (e.g., v0.26.0 defaults to 2025 data, v0.25.0 to 2024 data). Older superseded data files are removed.fixIf your analysis requires a specific older PDG data table, you may need to explicitly load it or use an older version of the `particle` library. Always be aware of which PDG data year is being used by default.
affects: All versions with yearly PDG updates
gotchaWhen creating user-defined particles, assigning 'random' PDG IDs can result in particles with undefined or incorrect internal quantum numbers and properties.fixExercise caution when manually defining particles. Ensure that any custom PDG IDs are consistent with the standard PDG numbering scheme if you expect quantum numbers and other properties to be correctly inferred.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'particle'
The 'particle' library is not installed in your Python environment or the Python interpreter cannot locate it in its search path.
fixInstall the library using pip: `pip install particle`
AttributeError: 'Particle' object has no attribute 'MomentumSum'
You are attempting to access an attribute or method ('MomentumSum' in this case) that does not exist on the `Particle` object.
fixConsult the `particle` library's documentation to verify available attributes and methods, or ensure you are not misinterpreting an object's capabilities. For properties like momentum, one might access `p.momentum` or calculate sums manually if `MomentumSum` is not a defined method.
TypeError: 'Particle' object is not iterable
You are trying to iterate directly over a single `Particle` object where an iterable (like a list or tuple of particles) is expected, for example, in a loop or an unpacking assignment.
fixIf you intend to work with multiple particles, ensure you are using methods that return collections (e.g., `Particle.findall()`) or explicitly create a collection. If you are trying to unpack a single particle, ensure the syntax is correct (e.g., `(p,) = Particle.finditer(...)` if only one is expected, or just `p = Particle.from_pdgid(...)` for a single object).
ImportError: cannot import name 'PDGID' from 'particle'
The name 'PDGID' is either misspelled, or it is not directly available for import from the top-level 'particle' package, or the version of the library you are using has changed its import path.
fixEnsure correct casing and module path. The `PDGID` class is typically imported as `from particle import PDGID`.
Upgrade
Version history
1.0.0latest on PyPI · released Jun 25, 2026
Audit
Dependencies
pandasrequiredRequired for data handling and internal data tables.
attrsrequiredProvides classes without boilerplate, similar to Python's DataClasses.
hepunitsrequiredProvides units for the Scikit-HEP packages, used for physical quantities.