This module provides around 200 predefined units that are commonly used in the sciences. Additionally, it provides the Unit class which allows you to define your own units.


All examples in this tutorial are computable, so one can just copy and paste them into a Python shell and do something useful with them. All computations were done using the following setup:

>>> from sympy.physics.units import *

Dimensionless quantities

Provides variables for commonly written dimensionless (unit-less) quantities.

>>> 2*ten
>>> 20*percent
>>> 300*kilo*20*percent
>>> nano*deg

Base units

The SI base units are defined variable name that are commonly used in written and verbal communication. The singular abbreviated versions are what is used for display purposes, but the plural non-abbreviated versions are defined in case it helps readability.

>>> 5*meters
>>> milli*kilogram
>>> gram

Note that British Imperial and U.S. customary units are not included. We strongly urge the use of SI units; only Myanmar (Burma), Liberia, and the United States have not officially accepted the SI system.

Derived units

Common SI derived units.

>>> joule


Physical units and dimensions.

The base class is Unit, where all here defined units (~200) inherit from.

The find_unit function can help you find units for a given quantity:

>>> import sympy.physics.units as u
>>> u.find_unit('coul')
['coulomb', 'coulombs']
>>> u.find_unit(u.charge)
['C', 'charge', 'coulomb', 'coulombs']
>>> u.coulomb

Units are always given in terms of base units that have a name and an abbreviation:

>>> u.A.name
>>> u.ampere.abbrev

The generic name for a unit (like ‘length’, ‘mass’, etc...) can help you find units:

>>> u.find_unit('magnet')
['magnetic_flux', 'magnetic_constant', 'magnetic_flux_density']
>>> u.find_unit(u.magnetic_flux)
['Wb', 'wb', 'weber', 'webers', 'magnetic_flux']

If, for a given session, you wish to add a unit you may do so:

>>> u.find_unit('gal')
>>> u.gal = 4*u.quart
>>> u.gal/u.inch**3

To see a given quantity in terms of some other unit, divide by the desired unit:

>>> mph = u.miles/u.hours
>>> (u.m/u.s/mph).n(2)

The units are defined in terms of base units, so when you divide similar units you will obtain a pure number. This means, for example, that if you divide a real-world mass (like grams) by the atomic mass unit (amu) you will obtain Avogadro’s number. To obtain the answer in moles you should divide by the unit avogadro:

>>> u.grams/u.amu
>>> _/u.avogadro

For chemical calculations the unit mmu (molar mass unit) has been defined so this conversion is handled automatically. For example, the number of moles in 1 kg of water might be calculated as:

>>> u.kg/(18*u.mmu).n(3)

If you need the number of atoms in a mol as a pure number you can use avogadro_number but if you need it as a dimensional quantity you should use avogadro_constant. (avogadro is a shorthand for the dimensional quantity.)

>>> u.avogadro_number
>>> u.avogadro_constant

Values of constants are recommended by Committee on Data for Science and Technology (CODATA) as of 2014. See more at http://arxiv.org/pdf/1507.07956.pdf

class sympy.physics.units.Unit[source]

Base class for base unit of physical units.

>>> from sympy.physics.units import Unit
>>> Unit("meter", "m")

Other units are derived from base units:

>>> import sympy.physics.units as u
>>> cm = u.m/100
>>> 100*u.cm

Return a list of matching units names. if quantity is a string – units containing the string \(quantity\) if quantity is a unit – units having matching base units


>>> from sympy.physics import units as u
>>> u.find_unit('charge')
>>> u.find_unit(u.charge)
['C', 'charge', 'coulomb', 'coulombs']
>>> u.find_unit('volt')
['volt', 'volts', 'voltage']
>>> u.find_unit(u.inch**3)[:5]
['l', 'cl', 'dl', 'ml', 'liter']