iconv - macOS


iconv is a command-line utility in macOS used to convert the character encoding of text from one format to another. It supports a wide range of encoding schemes, making it highly valuable for scripting, data processing, and software development, especially when handling files with different encodings or preparing data for internationalization.


The basic syntax of the iconv command is:

iconv [options] -f from-encoding -t to-encoding [inputfile...]
  • from-encoding: Specifies the character encoding of the input file.
  • to-encoding: Specifies the desired character encoding for the output.

If no input file is specified, iconv reads from the standard input.


  • -f, --from-code=NAME:
    Specify the encoding of the input text. Required unless piping input from another command.

  • -t, --to-code=NAME:
    Specify the encoding for the output text. Required.

  • -c:
    Omit invalid characters from output instead of stopping the conversion.

  • -o FILE:
    Specify a file to output the results to, rather than using standard output.

  • -s, --silent:
    Suppress error messages about invalid or untranslatable characters.

  • -l, --list:
    List all known encoded character sets.

  • --verbose:
    Increase verbosity of the program, useful for debugging.


1. Converting a file from UTF-8 to ISO-8859-1:

iconv -f UTF-8 -t ISO-8859-1 input.txt > output.txt

2. Ignoring invalid characters during conversion:

iconv -c -f UTF-8 -t ASCII input.txt > output.txt

3. Listing available character encodings:

iconv -l

4. Converting input from standard input and output to a file:

echo 'Some UTF-8 text' | iconv -f UTF-8 -t ASCII -o converted.txt

Common Issues

  • Encoding Errors: When iconv encounters an untranslatable character, it will by default stop converting unless -c is used to ignore such characters.
  • Locale Settings: The behavior of iconv can be influenced by locale settings (LC_* environment variables). Ensure these are correctly set if unexpected conversions occur.


iconv can be integrated with shell scripts or used in combination with other commands for batch processing. For instance, converting all .txt files in a directory can be done with a simple loop:

for file in *.txt; do
  iconv -f UTF-8 -t ISO-8859-1 "$file" > "converted-$file"
  • nkf (Network Kanji Filter): Another tool for encoding conversion, popular for handling Japanese character encodings.
  • uconv: A tool similar to iconv with additional features like Unicode normalization.

For more detailed information and updates, refer to the iconv man page by entering man iconv in your terminal or visiting the GNU libiconv library documentation.