iconv(1)

💖 NAME 💖

iconv — convert text from one character encoding to another 🦋

okay so bestie, listen: this is iconv, and she lives in the General Commands Manual (section 1, the girlies). she takes your text and swaps the character encoding, like a translator but for bytes instead of words. iconic. periodt. ✨

---

📝 SYNOPSIS 📝

iconv [options] [-f from-encoding] [-t to-encoding] [inputfile ...]

---

🌸 DESCRIPTION 🌸

The iconv program reads in text in one encoding and outputs the text in another encoding. fr fr that's the whole vibe.

If no input files are given, or if it is given as a dash (-), iconv reads from standard input. If no output file is given, iconv writes to standard output. no cap.

If no from-encoding is given, the default is derived from the current locale's character encoding. If no to-encoding is given, the default is derived from the current locale's character encoding too. so basically she just mirrors your locale unless you tell her otherwise 💅

---

✨ OPTIONS ✨

• --from-code=from-encoding, -f from-encoding — Use from-encoding for input characters. this is you telling her "hey, the stuff I'm feeding you is in THIS encoding" 🍓
• --to-code=to-encoding, -t to-encoding — Use to-encoding for output characters. and this is you being like "and spit it back out in THIS one" 👑

If the string //IGNORE is appended to to-encoding, characters that cannot be converted are discarded and an error is printed after conversion. (Characters that cannot be decoded are treated as an error with or without this flag.) lowkey chaotic but okay bestie 🤪

If the string //TRANSLIT is appended to to-encoding, characters being converted are transliterated when needed and possible. This means that when a character cannot be represented in the target character set, it can be approximated through one or several similar looking characters. Characters that are outside of the target character set and cannot be transliterated are replaced with a question mark (?) in the output. it's giving "close enough" energy 💀

• --list, -l — List all known character set encodings. the full menu, the whole menu, every single one 👀
• -c — Discard characters that cannot be converted instead of terminating when encountering such characters. POSIX requires that this option does not change the exit status of the program. so like, she keeps going instead of dramatically storming out 🚪💨
• --output=outputfile, -o outputfile — Use outputfile for output. put it in a file instead of screaming it into your terminal 🎀
• --silent, -s — This option is ignored; it is provided only for compatibility. literally does nothing. a decorative ghost 👻
• --verbose — Print progress information on standard error when processing multiple files. she's narrating her little journey 🗣️
• --help, -? — Print a usage summary and exit. your "help me pls" button 🆘
• --usage — Print a short usage summary and exit. the sparknotes version, the tl;dr, the summary bestie ✨
• --version, -V — Print the version number, license, and disclaimer of warranty for iconv. receipts, legal receipts 💅

---

🚦 EXIT STATUS 🚦

Zero on success, nonzero on errors. clean. simple. she either slayed or she didn't ✅❌

---

🌈 ENVIRONMENT 🌈

Internally, the iconv program uses the iconv(3) function, which in turn uses gconv modules (dynamically loaded shared libraries — yes, actual shared libraries, she's fancy like that) to convert to and from a character set. Before calling iconv(3), the iconv program must first allocate a conversion descriptor using iconv_open(3). The operation of the latter function is influenced by the setting of the GCONV_PATH environment variable:

• If GCONV_PATH is not set, iconv_open(3) loads the system gconv module configuration cache file created by iconvconfig(8) and then, based on the configuration, loads the gconv modules needed to perform the conversion. If the system gconv module configuration cache file is not available, then the system gconv module configuration file is used. ok so she checks the cache first, then falls back fr fr 🍓
• If GCONV_PATH is defined (as a colon-separated list of pathnames), the system gconv module configuration cache is not used. Instead, iconv_open(3) first tries to load the configuration files by searching the directories in GCONV_PATH in order, followed by the system default gconv module configuration file. If a directory does not contain a gconv module configuration file, any gconv modules that it may contain are ignored. If a directory contains a gconv module configuration file and it is determined that a module needed for this conversion is available in the directory, then the needed module is loaded from that directory, the order being such that the first suitable module found in GCONV_PATH is used. This allows users to use custom modules and even replace system-provided modules by providing such modules in GCONV_PATH directories. she's got main character energy and she WILL swap out the system's modules if you ask nicely 💅

---

📁 FILES 📁

• /usr/lib/gconv — Usual default gconv module path. the usual hangout spot 📍
• /usr/lib/gconv/gconv-modules — Usual system default gconv module configuration file. the usual config 🎀
• /usr/lib/gconv/gconv-modules.cache — Usual system gconv module configuration cache. the usual cache, the fast lane ⚡

Depending on the architecture, the above files may instead be located at directories with the path prefix /usr/lib64. so check /usr/lib64 bestie, don't get caught lacking 🫶

---

📜 STANDARDS 📜

POSIX.1-2008. certified, official, approved by the girlies who write standards 👑

---

🕰️ HISTORY 🕰️

POSIX.1-2001. she's been around. a legacy. an icon. respect her 💜

---

🧪 EXAMPLES 🧪

Convert text from the ISO/IEC 8859-15 character encoding to UTF-8:

$ iconv -f ISO-8859-15 -t UTF-8 < input.txt > output.txt;

The next example converts from UTF-8 to ASCII, transliterating when possible:

$ echo abc ß α € àḃç | iconv -f UTF-8 -t ASCII//TRANSLIT;
abc ss ? EUR abc

see how the ß became ss, the α became a ?, the € became EUR, and the àḃç became abc?? that's the //TRANSLIT magic doing her little dance ✨🦋

---

👀 SEE ALSO 👀

locale(1), uconv(1), iconv(3), nl_langinfo(3), charsets(7), iconvconfig(8)

---

okay that's the whole thing bestie, go convert some encodings, you got this 🫶💖 this page is from Linux man-pages 6.20, dated 2025-09-21 — slay, and happy encoding ✨💅