Skip to main content

An object-oriented Python interface to udunits

Project description





PyPI version

An object-oriented Python interface to udunits2 built with cython.


gimli.units requires Python 3 and udunits2.

Apart from Python, gimli has a number of other requirements, the main one being udunits2. udunits2 is the unit conversion C library that gimli wraps using cython. The easiest way to install udunits2 is through Anaconda (see the Install section), or yum (as udunits2-devel on ubuntu-based Linux). It can, however, also be compiled and installed from source. You can get the source code either as a .tar.gz or from GitHub.

All other requirements are available using either pip or conda. To see a full listing of the requirements, have a look at the project’s requirements.txt file.

If you are a developer of gimli you will also want to install additional dependencies for running gimli’s tests to make sure that things are working as they should. These dependencies are listed in requirements-testing.txt.


To install gimli, first create a new environment in which gimli will be installed. This, although not necessary, will isolate the installation so that there won’t be conflicts with your base Python installation. This can be done with conda as:

$ conda create -n gimli python=3
$ conda activate gimli

Stable Release

gimli, and its dependencies, can be installed either with pip or conda. Using pip:

$ pip install gimli.units

Using conda:

$ conda install gimli.units -c conda-forge

From Source

After downloading the gimli source code, run the following from gimli’s top-level folder (the one that contains to install gimli into the current environment:

$ pip install -e .


Primarily, gimli.units is a Python library with an API that reflects that of the udunits2 library. gimli, however, also comes with a command-line interface.


You primarily will access gimli through gimli.units,

>>> from gimli import units

units is an instance of the default UnitSystem class, which contains all of the units contained in a given unit system. If you like, you can create your own unit system but, typically, the default should be fine.

To get a specific unit from the system, do so by passing a unit string to the Units class. For example,

>>> units.Unit("m")
>>> units.Unit("m/s")
>>> units.Unit("kg m-3")
>>> units.Unit("N m")

Every Unit instance has a to method, which returns a unit converter for converting values from one unit to another,

>>> lbs = units.Unit("lb")
>>> kgs = units.Unit("kg")
>>> kgs_to_lbs =
>>> kgs_to_lbs(1.0)

You can also construct units that are a combination of other units.

>>> ft_per_s = units.Unit("ft / s")
>>> m_per_s = units.Unit("m s-1")
>>>[1.0, 2.0])
array([0.3048, 0.6096])

Command-line interface

From the command line you can use gimli to convert values from one unit to another.

$ gimli --from=miles --to=ft --data=1.0

Values to convert are passed through the –data option as a comma-separated list of numbers. You can also provide values through files and use a dash for stdin.

$ echo "1.0" | gimli --from=cal --to=joule -

When reading from a file, gimli tries to preserve the format of the input file,

$ cat values.csv
1.0, 2.0, 3.0
4.0, 5.0, 6.0
$ gimli --from=knot --to=m/s values.txt
0.514444, 1.028889, 1.543333
2.057778, 2.572222, 3.086667


Development Lead

  • Eric Hutton (@mcflugen)


None yet. Why not be the first?

Changelog for gimli

0.3.0 (2021-11-16)

  • Added support for a wider range of array dtypes (#13)
  • Fixed AttributeError when deallocating UnitSystem after exiting Python (#12)
  • Fixed –version option for the gimli command (#11)

0.2.1 (2021-03-02)

  • Fixed a bug caused by passing a single value to the cli (#10)
  • Added content to the README, mainly installation and usage instructions (#9)

0.2.0b1 (2021-02-22)

  • Added release and prerelease actions to publish on PyPI and TestPyPI (#8)
  • Change name of package to gimli.units (#7)

0.2.0b0 (2021-02-20)

  • Added gimli command-line interface (#6)
  • Better handling of multi-dimensional and non-contiguous arrays (#5)
  • Fixed a issue that caused a segmentation fault when using dimensionless units (#4)

0.1.1 (2021-02-17)

  • Created the gimli package (#1)
  • Set continuous integration using GitHub actions (#2)
  • Deploy to TestPyPI on a version tag (#3)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gimli.units-0.3.0.tar.gz (33.0 kB view hashes)

Uploaded source

Built Distributions

gimli.units-0.3.0-cp39-cp39-win_amd64.whl (101.4 kB view hashes)

Uploaded cp39

gimli.units-0.3.0-cp38-cp38-win_amd64.whl (101.4 kB view hashes)

Uploaded cp38

gimli.units-0.3.0-cp37-cp37m-win_amd64.whl (98.1 kB view hashes)

Uploaded cp37

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page