6 Font Configuration Files


One way the Oracle JDK maps logical font names to physical fonts is by using font configuration files. There may be several files to support different mappings depending on the host operating system version. The files are distributed with the JDK installation. You can edit or create your own font configuration files to adjust the mappings to your particular system setup, however these must be placed in conf/fonts, and are subject to implementation notes discussed below.

Font configuration files come in two formats: a properties format and a binary format. The properties format is described in detail in this document and can be used for user-defined configurations. The binary format is undocumented and used only for the JDK's predefined configurations; the corresponding files in properties format are available for reference as files with the .properties.src extension.

Supported Platforms

Font configuration files are implementation dependent. Not all implementations of the Java Platform use them, and the format and content vary between different runtime environments as well as between releases. The macOS implementation does not use font configuration files, as the mapping is hard coded in the source and cannot be changed in any way.

The Oracle JDK supports font configuration files on the host operating system as follows:
  • For Windows, font configuration files are required.

  • For macOS, font configuration files are unsupported.

  • For Linux and Solaris: the Oracle JDK is moving away from providing custom font configuration files on Linux platforms, as they are difficult to keep up to date across distributions and versions. A distribution that has control over the fonts on the system can continue to provide this custom file. If the JRE finds a custom file that exactly matches the distribution and version it will use it. If no exact match is found, the JRE dynamically creates the file at runtime. These generated files are placed in a location determined by the implementation. They should be considered implementation internal: they are not user editable and do not follow the syntax as described in this specification.

Loading Font Configuration Files

The JDK places any files that it provides in $JDKHOME/lib. Do not modify that location. Instead, put any updates or custom versions of the configuration files in $JDKHOME/conf/fonts. If you provide a custom configuration file, it must adhere to the implementation limitation that a font cannot contain more than 254 slots.

On platforms that support font configuration files, the runtime will look first in $JDKHOME/conf/fonts. In other words, a user-supplied file is preferred if it is a match.

The font configuration file for a host operating system is located as follows:

  • JavaHome - the JDK directory, as given by the java.home system property.
  • OS - a string identifying an operating system variant:
    • For Windows, empty.
    • For Solaris, empty.
    • For Linux, "RedHat", "SuSE", etc.
  • Version - a string identifying the operating system version.

The runtime uses the first of the following files it finds:


Files with a .properties suffix are assumed to be properties files as specified by the Properties class and are loaded through that class. Files without this suffix are assumed to be in binary format.

Names Used in Font Configuration Files


  • LogicalFontName - one of the five logical font names: serif, sansserif, monospaced, dialog, and dialoginput. In font configuration files, these names are always in lowercase.
  • StyleName - one of the four standard font styles: plain, bold, italic, and bolditalic. Again, these names are always in lowercase.
  • PlatformFontName - the name of a physical font, in a format typically used on the platform:
    • On Windows, a font face name, such as "Courier New" or "\uad74\ub9bc".
    • On Solaris and Linux, an xlfd name, such as "-monotype-times new roman-regular-r---*-%d-*-*-p-*-iso8859-1". Note that "%d" is used for the font size - the actual font size is filled in at runtime.
  • CharacterSubsetName - a name for a subset of the Unicode character set which certain component fonts can render. For Windows, the following names are predefined: alphabetic, arabic, chinese-ms936, chinese-gb18030, chinese-ms950, chinese-hkscs, cyrillic-iso8859-5, cyrillic-cp1251, cyrillic-koi8-r, devanagari, dingbats, greek, hebrew, japanese, korean, latin, symbol, thai. For Solaris and Linux, the following names are predefined: arabic, chinese-gb2312, chinese-gbk, chinese-gb18030-0, chinese-gb18030-1, chinese-cns11643-1, chinese-cns11643-2, chinese-cns11643-3, chinese-big5, chinese-hkscs, cyrillic, devanagari, dingbats, greek, hebrew, japanese-x0201, japanese-x0208, japanese-x0212, korean, korean-johab, latin-1, latin-2, latin-4, latin-5, latin-7, latin-9, symbol,thai. A font configuration file may define additional names to identify additional character subsets.
  • Encoding - the canonical name of the default encoding, as provided by java.nio.charset.Charset.defaultCharset().name().
  • Language - the language of the initial default locale.
  • Country - the country of the initial default locale.

Properties for All Platforms

Properties that are applicable to all platforms enable you to specify the font configuration format version, component font mappings, search sequences, exclusion ranges, proportional fonts, font file names, and appended font path.

Version Property


The complete property has the form:


Component Font Mappings


The keys have the forms:



The values are platform font names, as described in Names Used in Font Configuration Files.


Search Sequences


The keys have the form:






The values of all search sequence properties have the form:

  CharacterSubsetName , SearchSequenceValue




The runtime will first attempt to render a character with the MSGothic font. If that font doesn't provide a glyph for the character, it will attempt the Arial font. For 2D rendering, it will also try the Gulim font as well as any TrueType, OpenType, or Type 1 fonts in the system's standard font locations. For 2D rendering on Windows, if there is a system EUDC font registered with Windows, the runtime will also try this EUDC font.



Exclusion Ranges


The keys have the form:


The values have the form:

  Range , ExclusionRangeValue

  Char - Char

  HexDigit HexDigit HexDigit HexDigit
  HexDigit HexDigit HexDigit HexDigit HexDigit HexDigit

A Char is a Unicode character represented as a hexadecimal value.

Proportional Fonts


The keys have the form:


Space characters in the platform font name must be replaced with underscore characters (_).

The values have the form:


In values, space characters are left unmodified.


Font File Names


The keys have the form:




Appended Font Path


The key has the form:


The value has the form:

  Directory PathSeparator AppendedFontPathValue

The path separator is the platform dependent value of java.io.File.pathSeparator.

Properties for Windows



This information is only used for AWT, not for 2D. The /default suffix restricts use of the component fonts for this character subset to the character set of the default encoding; the /1252 suffix to the Windows-1252 character set. For accessing component font mappings and exclusion ranges, the character encoding suffix is omitted. For all other character subsets, the AWT character encoding is determined internally by the Java runtime.

Property for Solaris and Linux

The only property that is specific to Solaris and Linux is the AWT font path, which identifies platform directories that should be added to the X11 server font path.

The keys have the form:


The values have the form:

  Directory : AWTFontPathValue

The directories must be valid X11 font directories. The Java runtime ensures that the directories for all character subsets of a primary search sequence found by the search sequence lookup (see Search Sequences) are part of the X11 font path. The implementation assumes that all logical fonts use the same set of character subsets for a given environment of encoding, language, and country.