The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Encode::UTF8Mac - "utf-8-mac" a variant utf-8 used by OSX filesystem


  use Encode;
  use Encode::UTF8Mac;
  # some filename from osx...
  my ($filename) = <*.txt>;
  # it is possible to decode by "utf-8" but...
  $filename = Encode::decode('utf-8', $filename);
  # => "poke\x{0301}mon.txt" (NFD é)
  #        ^^^^^^^^^ 2 unicode strings: "LATIN SMALL LETTER E" and "COMBINING ACUTE ACCENT"
  # probably you want these unicode strings.
  $filename = Encode::decode('utf-8-mac', $filename);
  # => "pok\x{00E9}mon.txt" (NFC é)
  #        ^^^^^^^^ single unicode: "LATIN SMALL LETTER E WITH ACUTE"


Encode::UTF8Mac provides a encoding named "utf-8-mac".

On OSX, utf-8 encoding is used and it is NFD (Normalization Form canonical Decomposition) form. If you want to get NFC (Normalization Form canonical Composition) character you need to use Unicode::Normalize's NFC().

However, OSX filesystem does not follow the exact specification. Specifically, the following ranges are not decomposed.


iconv (bundled Mac) can use this encoding as "utf-8-mac".

This module adds same name "utf-8-mac" encoding for Encode, it encode/decode text with that rule in mind. This will help when you decode file name on Mac.

See more information and Japanese example:

Encode::UTF8Mac makes you happy while handling file names on MacOSX


  • Encode::decode('utf-8-mac', $octets)

    Decode as utf-8, and normalize form C except special range using Unicode::Normalize.

  • Encode::encode('utf-8-mac', $string)

    Normalize form D except special range using Unicode::Normalize, and encode as utf-8.

    OSX file system change NFD automatically. So actually, this is not necessary.


  use Encode;
  use Encode::Locale;
  # change locale_fs "utf-8" to "utf-8-mac"
  if ($^O eq 'darwin') {
      require Encode::UTF8Mac;
      $Encode::Locale::ENCODING_LOCALE_FS = 'utf-8-mac';
  $filename = Encode::decode('locale_fs', $filename);

If you are using Encode::Locale, you may want to do this.


Encode::Locale - provides useful "magic" encoding.

Unicode::Normalize::Mac - this module uses it internally.


Naoki Tomita <>


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.