This manual is for GNU units (version 2.25) on Microsoft Windows®.

Copyright © 2016--2024,2026 Free Software Foundation, Inc.

Introduction
************

The units program converts quantities expressed in various systems of measurement to their equivalents in other systems of measurement.  Like many similar programs, it can handle multiplicative scale changes; but it can also handle nonlinear conversions such as Fahrenheit to Celsius.  The program can also perform conversions from and to sums of units, such as converting between meters and feet plus inches.

Basic operation is simple: at the You have: prompt, enter the unit from which you want to convert; at the subsequent You want: prompt, enter the unit to which you want to convert. For example,

     You have: ft
     You want: m
             * 0.3048
             / 3.2808399

In other words, 1 foot is equal to 0.3048 meter (exactly), and 1 meter is equal to approximately 3.2808339 feet.

To quit the program, press Ctrl-C or Ctrl-Z; with the latter, you may need to press Enter.

Documentation
=============

The program's features are described in detail in the user manual Units Conversion.  If you created a Start Menu folder for units, you can access the user manual from the Start Menu by scrolling until the units (or whatever name you specified during installation) folder appears, clicking on it, and clicking Units User Manual from the submenu that appears.

Procedures for accessing items from the Start Menu vary among Windows versions and configurations.  Those described here apply to Windows 10.

Build
=====

Beginning with version 2.21, units is compiled as a 64-bit executable.  If a previous 32-bit installation is detected, the installer prompts you to remove it; if you decline, the installation is aborted.

Running units
*************

Start Menu
==========

If you created a Start Menu folder for units, you can run the program from the Start Menu by scrolling until the units (or whatever name you specified during installation) folder appears, clicking on it, and clicking units from the submenu that appears.  If Windows Terminal is installed, there will be an additional shortcut units WT that uses Windows Terminal, with Unicode support.

Desktop Shortcut
================

If you created a Desktop shortcut during installation, you can start the program by double clicking the shortcut.  If Windows Terminal is installed, two shortcuts will have been created.

Windows Console Applications
============================

Beginning with Windows 10, there are two host applications that shortcuts can use: Windows Console Host, the traditional console, and Windows Terminal, a newer terminal emulator with many additional features.  Windows Terminal supports Unicode; Windows Console Host does not.

Windows Terminal is included with Windows 11; on Windows 10, you may need to obtain it from the Microsoft Store.  It is not available for earlier versions of Windows.

The installation process creates a shortcut that uses Windows Console Host; if Windows Terminal is installed, the process creates an additional shortcut units WT that uses Windows Terminal, with Unicode support.

Windows Console Host
--------------------

When units is run in Windows Console Host, it will always appear in a new window that displays the units icon; this is the same behavior as with previous versions of units.  There is no support for Unicode.  The terminal window opened by this shortcut is shown in fig:ex1.

units Terminal Window
Figure: Terminal Window from units Windows Console Host Shortcut

The window appearance---including font, font size, and colors---can be changed by right-clicking in the title bar and selecting Properties.

Windows Terminal
----------------

In addition to support for Unicode, Windows Terminal's features include multiple tabs, panes, a GPU-accelerated text-rendering engine, and the ability to create your own themes and customize text, colors, backgrounds, and shortcuts.  When units is started from a Windows Terminal shortcut, the behavior depends on how Windows Terminal is configured.  By default, each instance of units will run in a new window that displays a cmd icon.  The configuration can be changed to have units run in a new tab in an existing Windows Terminal window.

The Windows Terminal shortcut created by the installation process is

     wt.exe cmd /c title units && chcp 65001>NUL && "C:\Program Files\GNU\units\units.exe"

The Windows command interpreter cmd is needed because several commands are to be run: the first sets the window title to units; the second sets the Windows code page to UTF-8. The window opened by this shortcut shown in fig:ex2.

units Terminal Window
Figure: Terminal Window from units Windows Terminal Shortcut

More units are available because definitions using UTF-8 are included. Note that the tab shows the cmd icon rather than the units icon.  Unlike with the Windows Console Host, there is no way to change the window appearance (other than tab color) on a per-instance basis.

If you are familiar with Windows Terminal, you can create a profile for units and determine the behavior and appearance of the window or tab.  In such a profile, you can specify, among others, the Command line, the Starting directory, and the Icon.  To have the units icon display on the Windows Terminal tab, you need to specify the units icon; you can specify either the executable C:\Program Files\GNU\units\units.exe or the units icon file C:\Program Files\GNU\units\unitsprog.ico. Unless the Windows locale is set to UTF-8, the command line will need to set the code page to 65001, e.g.,

     cmd /c chcp 65001>NUL && "C:\Program Files\GNU\units\units.exe"

If you were to create a profile named units with the appropriate settings, you could change the shortcut to

     wt.exe -p units

The easiest way to create a custom profile is to select Settings from the Windows Terminal dropdown menu and then select + Add a new profile (you may need to scroll if there are many existing profiles).  An example profile for units in Windows Terminal Settings is shown in fig:ex3.

Windows Terminal profile
Figure: Example Windows Terminal Profile for units

The command line sets UTF-8 and sets the terminal window to blue text on a white background; the starting directory is USERPROFILE.  The units icon appears in the terminal tab.

The window opened by a shortcut using the custom units profile is shown in fig:ex4.

units Terminal Window
Figure: Terminal Window with units Profile

Note that the units icon is displayed in the tab.

The Additional Settings section of the profile menu allows additional customization.  See the Microsoft documentation for Windows Terminal for more information.

Command Line
============

Running units from the command line affords the greatest flexibility---especially the ability to specify startup options.  There are several ways to run units from the command line.

Command Prompt window. Start an instance of the Windows command prompt.  Click in the taskbar search box and enter cmd; Command Prompt should appear at or near the top of the list of results.  Click on Command Prompt, or just press Enter if it is already highlighted; a command-prompt window should appear.  Alternatively, right-click on the Start Menu icon and select Command Prompt from the menu.

Start the units program, giving any desired options after the command. If you added the units directory to PATH, you can simply type units and press Enter; if not, you will need to enter the complete path name, enclosing it in double quotes if it contains spaces, e.g., "C:\Program Files\GNU\units\units.exe".

With some options, e.g., --help, units displays information about the program and then exits.  For these options, running from a command-prompt window is the only practical option.

Taskbar Search Box. You can also run units directly from the taskbar search box.  Click in the search box and enter units, along with any options you wish to specify; units should be at or near the top of the list of results.  Click on units, or simply press Enter if units is already highlighted; units should appear in a new console window.

Start Menu Run Box. Click in the taskbar search box and enter Run; Run should be at or near the top of the list of results.  Click on Run, or just press Enter if Run is already highlighted; the Run box should appear.  Enter units, along with any options you wish to specify, and press Enter; units should appear in a new console window.

Using the Run box requires an additional step, but has the advantage of remembering recent commands; this can be helpful if you frequently invoke units with the complete path name or with options.

Startup Options
===============

The behavior of units can be customized by specifying one or more options at startup.  For example, you can enter

     units -dmax

to have units show results to the maximum available precision.  The options are described in detail under Invoking Units (Units Conversion).

Note: unlike most Windows command-line programs, options to units must begin with - rather than /.  The options are also case sensitive.

It's probably easiest to specify options when units is started from a command-prompt window.  Options can also be given from the Run box on the Start Menu just as they are given from a command window; however, if you give an invalid option or an invalid value, the console window that appears will probably close before you can see the error message.

If you frequently use a particular option, you can modify a shortcut on the Desktop or the Start Menu to include it.  Select the appropriate shortcut, right click and select Properties, and select the Shortcut tab.  In the Target box, append the desired option(s) and click OK.  For example, if the Target box contains

     "C:\Program Files\GNU\units\units.exe"

and you always wanted units to show values to the maximum available precision, you could change this to

     "C:\Program Files\GNU\units\units.exe" -dmax

Be careful to enter the option(s) correctly---otherwise the units window will probably close before you can see the error message that results from an invalid option.  As mentioned, this approach cannot be used with options such as --help that simply display information about the program and then exit.

If you wish, you can have different shortcuts that give different options---but keeping track of which shortcut does what can quickly become a challenge. If you frequently need to use different options, the best approach is to set the options interactively (see Setting Options Interactively (Units Conversion), the main units manual, or start units from the command line.

With Windows Console Host, you can customize the appearance of a window started from a shortcut, specifying the font and size, the foreground and background colors, and the size of the window.  If you want to copy and paste from the units window, right click on the window title bar, select the Options tab and ensure that the box next to QuickEdit Mode is checked.

With Windows Terminal, you need to create a profile for units to change the window appearance.

Interactive Commands
====================

Typing help at either prompt displays a short help message.  You can also type help followed by a unit name.  This will invoke a pager on the units database at the point where that unit is defined. You can read the definition and comments that may give more details or historical information about the unit.  If your pager allows, you may want to scroll backwards, e.g. with b, because sometimes a longer comment about a unit or group of units will appear before the definition.  You can generally quit out of the pager by pressing q.

Typing search TEXT will display a list of all of the units whose names contain TEXT as a substring along with their definitions. This may help in the case where you aren't sure of the right unit name.

Typing version will display the units version number; unlike the --version option, only the version number is shown, regardless of any other settings.  Full information is available with the info command.

Typing info will display the same information as the --info option, described in Invoking Units (Units Conversion), the main units manual.

Many values set by command-line options can also be set interactively by typing set OPTION=VALUE; typing set OPTION will show the value for that option.  Typing set will show a list of options that can be set; options set to other than default values will have a prepended *. See Setting Options Interactively (Units Conversion).

Command Editing
===============

At present, units for Windows does not include readline support (see Readline Support (Units Conversion)).  But both intraline editing and command history are available just as they are with any instance of the Windows command prompt---see the Windows documentation for doskey for a complete description.

Command editing may not be available if you start units from a different command interpreter.

Uninstalling Units
******************

Unless you declined to create a Start Menu folder for units, you can uninstall units from the Start Menu by scrolling until the units (or whatever name you specified during installation) folder appears, clicking on it, and selecting Uninstall units from the submenu that appears.  You will be asked to confirm that you want to remove units; if you click the Yes button, the uninstallation will proceed.  The process may take several seconds after the progress bar indicates completion as Windows updates its internal settings.

If you don't have a Start Menu folder for units, you can uninstall units via Settings > Apps > Apps & features. Scroll to find units version 2.25, and click the Uninstall button.  A dialog box will indicate that the application will be uninstalled; click the Uninstall button if you wish to proceed.  The process may take several seconds after the progress bar indicates completion as Windows updates its internal settings.

You can also uninstall units via Control Panel > Programs and Features. When the list is displayed, find units version 2.25 and click Uninstall.  You will be asked to confirm that you want to remove units; if you click the Yes button, the uninstallation will proceed.

Removing units from PATH
========================

By default, the installation adds the units installation directory to the PATH environment variable;  with versions earlier than 2.21, this directory was not removed from PATH upon uninstallation.  With version 2.21, the units directory is removed from PATH, and the units directory from a previous 32-bit installation is removed from PATH when a 64-bit version is installed.

If for some reason the units directory is not removed from PATH, you can remove it via the System Properties dialog.  In the taskbar search box, enter environment variables and select Edit environment variables for your account; this should open the Environment Variables dialog.  Select Path in the list of environment variables for your account or for the system, click the Edit... button, select the entry for units, and click the Delete button.

On most Windows versions, the System Properties dialog can be accessed by right-clicking the computer icon on the desktop.  The procedure for editing PATH on versions earlier than Windows 10 may be slightly different from the one above.

Icons and File Association
**************************

The installation process associates units data files with the notepad editor; double-clicking on the file icon opens the file for editing.  The installation process places two icons---unitsfile.ico and unitsprog.ico---in the installation folder.  The former is the default icon for units data files; the latter may be useful if you wish to create an additional shortcut.

Currency Definitions and CPI Updater
************************************

The script units_cur.py can be used to update currency exchange definitions and the US Consumer Price Index (if your system hides file extensions, this script will display as units_cur). The script requires Python (available from https://www.python.org/).

Installing Python
=================

If you want to use the currency updater, install Python if it is not already installed.  If you need to install Python, unless you have (or anticipate having) applications that depend on Python 2, the best choice is probably to install Python 3.

After installing Python, you should be able to run units_cur.py using the shortcut on the Start Menu, or if you have added the units installation directory to your PATH, from a command-prompt window.

When you first run units_cur.py, you may get a complaint about a missing module; for example

     ModuleNotFoundError: No module named 'requests'

If so, you will need to install the missing module.  The easiest way to do this is with the pip command; for example

     pip install requests

If you have Python 2.7.9 or later or Python 3.4 or later, you should have pip, though you may need to upgrade to the latest version.  If you do not have pip, you will need to install it manually; see the Python documentation or the Python website for instructions on how to do this.

Setting PATHEXT
===============

If you add .py to the PATHEXT environment variable, you can simply type units_cur to run the updater from a command-prompt window.  You can do this from the command prompt by typing

     set PATHEXT=%PATHEXT%;.py

but you'll need to do this with every new instance.  You can make a permanent change by adding ;.py to PATHEXT from the Advanced tab of the System dialog: click the Environment Variables button, find PATHEXT in either the list of User variables or the list of System variables; click the Edit button, make the change, and click OK.

Running the Updater
*******************

Updating from the Start Menu
============================

If you created a Start Menu folder for units, you can update the currency exchange definitions and the US CPI by finding that folder on the Start Menu and clicking the Currency updater entry.

Updating from a Command Prompt
==============================

If you have added the program installation directory to PATH, you can update the currency exchange definitions from the command prompt by typing units_cur.py (or simply units_cur if you have added .py to PATHEXT).

Automatic Updates
=================

The easiest way to keep currency values and US CPI up to date is by having the Windows Task Scheduler run units_cur.py on a regular basis.  The Task Scheduler is fussy about the format for the action, which must be an executable file; an entry might look something like

     C:\Windows\py.exe "C:\Program Files\GNU\units\units_cur.py"

if the Python launcher is in C:\Windows and the script is in C:\Program Files\GNU\units.  The program specified must start in the units installation directory; the starting directory must be specified without quotes.