How to convert a file to UTF-8 on Mac
You can do this with Note My, deliberately rather than by accident. Here is how to re-encode a file to UTF-8, and how to check afterwards that the bytes on disk really changed.
You have a file that looks perfectly fine. The accents are correct, the em dashes are where you left them. Then a build script, an importer or a colleague's tool rejects it, or produces nonsense from it, because the bytes on disk are not the encoding it expected. Nothing is wrong with the text. Something is wrong with how it is stored.
That is a conversion problem, and it has a specific answer in Note My: File ▸ Encoding ▸ Convert to Encoding…. This guide covers when that is the right command, when it is the wrong one, what the eighteen available encodings are, and how to check afterwards that the file on disk really changed.
All of this happens on your Mac. There is no account to make, nothing is uploaded, and a file you convert never leaves the machine on its way to a conversion service.
Convert or reload: the distinction that decides everything
The Encoding menu offers two commands that sound similar and do opposite things. Getting them the wrong way round turns a recoverable file into a damaged one, so it is worth being blunt about the difference.
| Reload with Encoding… | Convert to Encoding… | |
|---|---|---|
| What it acts on | The bytes already on disk | The text currently in the editor |
| What it does | Re-decodes them using a different encoding | Re-encodes the text, changing what will be written |
| Use it when | The text on screen looks wrong | The text on screen looks right |
| Typical symptom | Garbled accents, replacement characters | A downstream tool refuses the file |
Read the table by its third row and you will never confuse them again. If the text is wrong, reload. If the text is right, convert. Converting a document that is already garbled on screen does not repair it — it faithfully re-encodes the garble, and once you save, the original bytes are gone.
Convert the file you have open
-
Check that the text on screen is correct
Scroll to somewhere with non-ASCII characters — names with accents, currency symbols, quotation marks, anything CJK — and confirm they read properly. If they do not, stop: you want Reload with Encoding… first, and only then a conversion.
-
Note what the file is now
The status bar carries an encoding pill showing the document's current encoding. Click it and you get a Frequent section followed by one section per group, which is the same set of choices the menu offers.
-
Open the conversion sheet
Choose File ▸ Encoding ▸ Convert to Encoding…. It opens a sheet rather than acting immediately, so a mis-click on the menu costs you nothing.
-
Pick the target encoding
For most purposes that is plain UTF-8. Choose UTF-8 with BOM only when the consumer specifically wants a byte order mark — they are two separate entries precisely because it is a decision, not a detail.
-
Save the file
Conversion changes what will be written, not what is written. Press ⌘S. Until you do, the file on disk is untouched and the document carries the leading
*that marks unsaved work. A transient toast confirms the encoding change itself.
The eighteen encodings, and the seven kept to hand
Note My knows eighteen encodings, organised in three groups.
| Group | Encodings |
|---|---|
| Unicode (10) | UTF-8 · UTF-8 with BOM · UTF-16 LE · UTF-16 BE · UTF-16 LE BOM · UTF-16 BE BOM · UTF-32 LE · UTF-32 BE · UTF-32 LE BOM · UTF-32 BE BOM |
| Legacy and Western (4) | Windows-1252 · ISO-8859-1 · Mac Roman · KOI8-R |
| CJK (4) | Shift JIS · EUC-JP · GB18030 · Big5 |
Seven of those appear inline in the File ▸ Encoding menu as a frequent list, so the common cases are one click deep: UTF-8, UTF-8 with BOM, UTF-16 LE BOM, UTF-16 BE BOM, Windows-1252, ISO-8859-1 and Mac Roman. The rest live behind Other Encodings… in the same menu.
A note on direction of travel. Converting to Unicode is safe, because every character in a legacy encoding has a Unicode equivalent. Converting from Unicode to a legacy encoding is not symmetrical: Windows-1252 and Mac Roman hold a few hundred characters, and text containing anything outside that repertoire cannot survive the trip intact. Convert downward only when you know what the text contains and something genuinely requires it.
What conversion changes, and when it reaches the disk
Three things are worth being precise about.
- The text does not change. Conversion changes the byte representation, not the characters. What you read on screen before and after should be identical; if it is not, you converted a file that was already mis-decoded.
- The disk does not change until you save. The conversion sets what the document will be written as. The bytes on disk are still the old ones until ⌘S.
- Line endings are a separate axis entirely. They have a command of their own under File ▸ Line Endings and a status-bar pill of their own, so you choose LF or CRLF deliberately rather than having an encoding change quietly drag them along with it.
If you are handing the file to something strict, you often need both: convert the encoding, then convert the line endings, then save once. The line-ending pill shows Mixed ahead of anything else when a file has more than one kind, and warning on mixed line endings is on by default — so you will usually be told before you have to go looking.
A downward conversion followed by a save is the one move in this guide that can lose information. Characters the target encoding cannot represent do not survive it. Keep your own copy of anything irreplaceable before you convert away from Unicode.
The encoding every new file starts in
Settings has a dedicated Encoding pane — one of fourteen panes, reachable with ⌘, and findable by typing "encoding" into the sidebar search. Four settings live there.
| Setting | Default | What it governs |
|---|---|---|
| Default encoding for new files | UTF-8 | The encoding an untitled document starts in. |
| Legacy fallback | Windows-1252 | Your preferred legacy encoding for older, non-Unicode files. |
| Warn on binary | On | Tells you when a file you are opening does not look like text. |
| Preserve BOM | On | A byte order mark that was already there is kept rather than quietly dropped. |
The first of those governs new documents, which is exactly what you want: set it once and every untitled file you start from then on is already in the encoding your work expects. Files already open and files already on disk keep their own encoding until you convert them yourself, so a change of preference never rewrites work you did last year.
Checking the result byte by byte
A conversion is meant to be invisible on screen — the same characters, stored differently — so the proof is in the bytes. You can read those in the editor itself, on the document in front of you.
Turn on Show Invisibles in the toolbar, then open Settings ▸ Invisibles and set the marker style. There are three:
| Style | What a space looks like |
|---|---|
| Symbols (default) | A quiet middle dot, with an arrow for tab and a ring for a non-breaking space. |
| Code Points | An escape showing the Unicode code point — the same whatever the encoding. |
| Bytes | The hex bytes in the document's own encoding. |
The Bytes style is the one that answers the question, because it reflects what the file actually saves. A plain space is 20 in UTF-8 and 20 00 in UTF-16 LE. A non-breaking space is C2 A0 in UTF-8. Convert a document and watch those markers change and you have your confirmation, in the editor, without a hex viewer.
Where a character cannot be represented in the document's encoding, its marker carries a trailing *. Treat that asterisk as a warning sign after a downward conversion: it points at the exact character the target encoding cannot hold, so you can replace it, remove it, or stay with Unicode. Our encoding handling gives you that answer in the editor.
Converting many open files at once
When the same conversion has to happen to a dozen documents, you only need to do it once. Encoding conversion is one of the actions our macro recorder can capture, so you record the move and let it repeat across everything you have open.
Start recording with ⌥⌘R, run the conversion once, stop with ⌥⇧⌘R, and save the macro when the prompt appears. On playback (⌥⌘P) you get a scope chooser offering Current Tab or All Open Tabs — the second takes the conversion through every document you have open, in one pass. One ⌘Z afterwards reverses the whole run rather than just its last step, so a playback you regret costs one keystroke. A report sheet then shows Succeeded, Skipped and Failed counts, so you can see whether any tab still needs attention.
Because the run happens in tabs, every converted document is still in front of you when it finishes. Move through them, confirm the accents and symbols survived, and press ⌘S on each. If you are finishing up anyway, File ▸ Close All Tabs (⇧⌘W) asks once for the whole window and offers Save All, which writes every unsaved tab in one move. Nothing reaches the disk until you say so, so a run you have second thoughts about is a run you can simply close.
Before you convert a file other people depend on
Conversion is quick, and a bad conversion that nobody notices for three weeks is expensive. Six things to settle first.
- Read the text before you touch the encoding. If a single accented word looks wrong, the file was mis-decoded on open, and a conversion will write that mistake down permanently.
- Put an untouched copy somewhere. File ▸ Save a Copy As… (⌥⇧⌘S) and File ▸ Duplicate File… both leave you a second file on disk, and either takes seconds. That copy is the one you open if a conversion lands somewhere you did not intend, and making it costs less time than reading this sentence.
- Confirm which of the three decisions the other side cares about. Encoding, byte order mark and line ending are separate axes, and "it has to be UTF-8" from a colleague often means all three.
- Check for the trailing
*after a downward conversion. In the Bytes marker style it marks a character the document's encoding cannot represent. - Save, then verify against the disk. ⌘R for File ▸ Reload from Disk re-reads the file, and the encoding pill then describes what is really there rather than what you meant.
- Do not convert what you have not read. A file large enough that you have only seen the first screen is a file whose character repertoire you do not yet know. Our large-file engine keeps a long document moving while you scroll, so take a minute to look before you commit.
Troubleshooting
I converted to UTF-8 and the characters are still wrong
Then they were wrong before the conversion, and you have now written the wrong characters down. Reach for File ▸ Encoding ▸ Reload with Encoding… instead, which re-reads the bytes on disk and tries a different decoding. If you have already saved, go back to your copy of the original first — a save with a converted encoding overwrites the original bytes.
A stray character appears at the very start of the file
That is a byte order mark being shown by something that did not expect one. Convert to plain UTF-8 rather than UTF-8 with BOM. A byte order mark at the very start of a file is legitimate and is left where it is; the same character anywhere else in the document is zero-width junk, usually from concatenating files. Our hidden-character scanner, at Clean ▸ Clean Invisible / Special Characters…, will find it under the "Zero-width characters" category.
The receiving tool still complains after I converted
Check three things in order. First, that you saved. Second, the line endings — they are converted separately, and a strict tool may be objecting to CRLF rather than to the encoding. Third, use ⌘R for File ▸ Reload from Disk and look at the encoding pill: that tells you what is genuinely on disk now.
The file will not open as text in the first place
Press ⇧⌘O for File ▸ Open Anything as Text…, which forces open a file macOS has decided is not text. Warning on binary content is on by default, so you will be told if what arrives is not text at all.
I do not know what encoding the file is in
Open the file and read the status-bar encoding pill. Our encoding handling puts an answer there without your having to ask for one, on your Mac, with nothing uploaded and no account in the way. Let the text in front of you confirm it: if the accented characters, quotation marks and currency symbols read properly, the pill is right for every purpose you care about. If they do not, use File ▸ Encoding ▸ Reload with Encoding… and try the likely candidates — Windows-1252 or ISO-8859-1 for Western European text, Shift JIS or EUC-JP for Japanese, GB18030 for Simplified Chinese, Big5 for Traditional. Work through them until the text looks right, and only then convert.
I opened the conversion sheet and changed my mind
Dismiss it. Nothing has reached the disk in any case: a conversion changes what the document will be written as, and the bytes on disk stay exactly as they were until the next save.
Habits that make conversion routine
Once the distinction between reloading and converting is settled, the rest of the work is a short set of habits. These are the ones worth keeping.
- Survey the folder first. Find in Folder searches across a whole directory tree, so you can see every file that carries the character or the marker you are worried about before you open anything. It reads and reports; it never writes, so a survey costs you nothing.
- Fix the character rather than lose it. If a downward conversion is going to drop a smart quote or a stray symbol, our find and replace will sweep the whole set of documents you have open in one pass, and you convert afterwards with the repertoire already inside the target encoding.
- Confirm with the Bytes marker style. Turn on Show Invisibles, set the style to Bytes, and the hex behind each character tells you the conversion took. It is the fastest confirmation there is, and it happens in the document you are already reading.
- Let the safety net do its job. Our auto-recovery safety net is on from the moment you open the app, looking after the unsaved work in every tab, so an afternoon of conversions comes back where you left it if the Mac restarts under you.
- Treat encoding and line endings as two deliberate decisions. Two menus, two choices, one save — which means you can hand a strict importer exactly the combination it asks for instead of guessing at a single blunt setting.
- Set the new-file default once. Put Settings ▸ Encoding where your work lives and every untitled document starts correct, so most files never need converting at all.
Frequently asked questions
What is the difference between Reload with Encoding and Convert to Encoding?
They are opposites. Reload re-decodes the bytes already on disk using a different encoding, which is how you rescue a file that was read wrongly. Convert re-encodes the text you currently have, which changes what gets written when you save. If the text on screen is wrong you want reload; if it is right you want convert.
Should I choose UTF-8 or UTF-8 with BOM?
Plain UTF-8 unless something specifically asks for the byte order mark. They are two separate entries in the encoding list so that the choice is deliberate. Preserve BOM is on by default, so a file that arrived with one keeps it unless you convert away from it.
How do I convert several files in one go?
Open them as tabs, record the conversion once with our macro recorder, and play it back with the scope set to All Open Tabs. A report sheet then gives you Succeeded, Skipped and Failed counts, so you can see at a glance where the run got to. Then save: ⌘S in each tab, or — if you are finishing up anyway — File ▸ Close All Tabs (⇧⌘W), whose single sheet offers Save All and writes the whole set in one move.
Does converting the encoding change my text?
Not the characters, only how they are stored — provided the target encoding can represent them. Going to a Unicode encoding is always safe. Going down to Windows-1252, Mac Roman or a CJK encoding is only safe if the text stays inside that encoding's repertoire.
How do I check what encoding a file is in?
The status-bar encoding pill shows the current encoding, and clicking it lists the frequent set plus every group. To see the bytes themselves, turn on Show Invisibles and set the marker style to Bytes in Settings ▸ Invisibles.
How do I fix mixed line endings as well?
Line endings have a command of their own, so you can set them exactly: File ▸ Line Endings offers LF, CRLF, CR and Preserve Current Format, plus Show Line Ending Details… The status-bar pill reads Mixed when a file contains more than one kind, and warning on mixed endings is on by default, so you are told before it becomes somebody else's problem. Convert the encoding, set the line endings, save once.