The Unix `units` program is one of the most underrated command-line tools. It is not a simple lookup table; it is a full-fledged dimensional analysis engine that can convert between thousands of units, handle derived units, perform arithmetic, and even read from standard input for scripting. This guide will walk you through the essential workflows, advanced techniques, and common pitfalls, so you can use `units` with confidence in daily tasks, engineering checks, and automation.

The most common way to use `units` is interactive mode. Simply type `units` in your terminal, and you will see a prompt: `You have:`. Type the unit you want to convert from, then `You want:` for the target unit. For example:

``` You have: 12 inches You want: centimeters30.48 / 0.032808399 ```

The output shows two numbers: the multiplication factor (12 inches = 30.48 cm) and the reciprocal (1 cm = 0.0328... inches). If you only need one result, use the `-1` flag to suppress the reciprocal.

For one-off conversions, use command-line arguments:

``` units "5 miles" "kilometers" ```

This prints the result directly. Note that quotes are essential when the unit contains a space (e.g., "square feet"). Without quotes, the shell splits the argument.

`units` uses a text database (usually `/usr/share/units/definitions.units`) that defines units, prefixes, and conversion factors. You can search this database with the `-l` (list) flag:

``` units -l "meter" ```

This shows all units whose names contain "meter". To see the full definition of a unit, use `-v` (verbose):

``` units -v "nautical mile" "meters" ```

The verbose output shows the exact mathematical relationship. This is invaluable when you suspect a unit is defined differently in different contexts (e.g., "gallon" vs. "imperial gallon").

Tip: You can extend the database with your own custom units. Create a file called `~/.units` and add lines like:

``` my_weird_unit 123.45 meters ```

Then restart `units`. This is perfect for project-specific units (e.g., "1 floor = 3.2 meters").

`units` is not limited to simple conversions. You can use arithmetic operators `+`, `-`, ``, `/`, and parentheses. For example:

``` units " (5 kg + 2 lb) / 3 " "grams" ```

This calculates the total mass in grams. The program correctly handles mixed units because it converts everything to a common base internally.

You can also define compound units directly:

``` units "60 mph" "feet per second" ```

Output: `88 ft/s`. The program understands "per" as division and handles derived units like `Nm` (newton-meter) or `J/s` (watts).

Advanced trick: Use `^` for powers, but be careful with negative exponents. For example:

``` units "9.81 m/s^2" "ft/s^2" ```

The `^2` applies to the second, not to the whole expression. If you need `(m/s)^2`, write `" (m/s)^2 "`.

One of the most powerful uses is checking the consistency of equations. Suppose you have a formula for pressure drop: `ΔP = f(L/D)(ρv^2 / 2)`. You can verify the units of each term:

``` units " (kg/m^3)(m/s)^2 " "Pa" ```

If the result is a number (like 1), the units are consistent. If you get an error like `conformability error`, the dimensions mismatch. This is a fast way to catch mistakes in physics or engineering calculations before you even plug in numbers.

Practical workflow: Write your equation as a `units` expression, replacing constants with 1. Then convert to the expected output unit. If the conversion factor is not a pure number, your equation is dimensionally wrong.

For shell scripts, use the `terse` (or `-t`) flag to suppress the reciprocal and extra formatting:

``` result=$(units -t "3.7 liters" "cups") echo "Cups: $result" ```

The output is just the number (e.g., `15.638...`). To get a fixed precision, pipe through `awk` or use `printf`:

``` printf "%.2f\n" $(units -t "1 acre" "square meters") ```

If you need to handle errors gracefully, check the exit code. A non-zero exit code means the conversion failed (e.g., incompatible dimensions). For example:

``` if units -t "5 volts" "amps" >/dev/null 2>&1; then echo "Valid conversion" else echo "Dimension mismatch" fi ```

Important: When scripting, always quote your units. Unquoted strings with `` or `/` will be expanded by the shell, causing silent errors.

Temperature is tricky because it is not a simple multiplicative conversion. `units` handles this with special syntax. To convert from Celsius to Fahrenheit:

``` units "tempC(25)" "tempF" ```

Output: `77`. The `tempC()` and `tempF()` functions accept a numeric argument. For absolute temperature differences (e.g., a 5°C rise), use `tempdiff()`:

``` units "tempdiff(5)" "tempF" ```

This gives `9°F` because a difference of 5°C equals 9°F. Never use regular multiplication for temperatures—it will produce nonsense.

`units` is case-sensitive. `M` is mega (10^6), but `m` is milli (10^-3). `Pa` is pascal, but `pa` is not a unit. Always double-check capitalization.

The program accepts both `meter` and `meters`, but not irregular plurals like `feet` (which is fine) vs. `foot` (also fine). However, some units like `inch` become `inches`—both work. If unsure, use `-l` to search.

`60 mph` is fine, but `60 miles per hour` also works. However, `60 mile per hour` (singular) is also accepted. Be consistent. When using division, always enclose the numerator and denominator in parentheses if they contain spaces: `" (5 kg) / (3 m^2) "`.

Some units use Unicode (e.g., `µ` for micro). The database may or may not support them. To be safe, use ASCII equivalents like `u` for micro (e.g., `um` for micrometer).

`units` uses arbitrary-precision arithmetic, so you can convert 1e-30 meters to femtometers without floating-point errors. But note that the output may use scientific notation. Use `format` (e.g., `format "%f"`) to control the output.

If you need to convert many values in a loop, avoid starting `units` for each conversion—it loads the database each time, which is slow. Instead, use the `-f` flag with a script file, or feed a batch of conversions via standard input:

``` echo -e "1 meter feet\n2 meters feet\n3 meters feet" | units -t ```

This processes all lines in one run, printing one result per line. For large datasets, this is significantly faster.

By default, `units` shows two numbers. You can change this with `-o` (output format) and `-f` (format string). For example:

``` units -o "%.3f" -t "1 mile" "kilometers" ```

This prints `1.609` with three decimal places. The `-o` flag uses the same syntax as `printf`.

Always test with `-v` when using an unfamiliar unit to confirm its definition.

Keep a local `.units` file for project-specific constants (e.g., "1 server_rack = 42 U").

Use `units` inside your editor via a shell alias like `uc` to convert highlighted numbers without leaving your workflow.

Never trust a conversion that produces a dimension error—the program is telling you that your equation is wrong, not that it failed.

With these techniques, `units` becomes more than a converter—it becomes a verification tool, a scripting component, and a reliable partner in any technical work. Start with the basics, then gradually incorporate arithmetic and custom definitions. You will soon