Mac Text Replacement Not Working? Here's Every Fix

You set up omw to type “On my way!” and it works in Messages. Then you try it in Slack, or Word, or a Google Doc, and nothing happens.

Text Replacements are the Mac’s built-in text expander, and they fail for a small number of reasons. Here’s each one, in the order worth checking.

The quick answer

Try the shortcut in TextEdit first. If it expands there, your replacement is fine and the app you were in either has the feature switched off (Edit → Substitutions → Text Replacement) or doesn’t use Apple’s text system at all. If it doesn’t expand in TextEdit either, check the shortcut’s spelling in System Settings → Keyboard → Text Replacements… and remember it only expands after you type a space or punctuation.

1. Test it in TextEdit

This one step tells you which half of the problem you have. Open TextEdit, make a new document, type your shortcut and press Space.

If it expands, the replacement itself is fine, and the rest of this article is about the app you were using. If it doesn’t, the problem is the replacement or the Mac, so go to step 3.

2. Turn it on in the app

Text Replacement is a per-app switch in every app that has an Edit menu built on Apple’s text system: TextEdit, Mail, Notes, Pages, Messages and many others. It can be off in one app and on in the rest.

Click into a text field, then open Edit → Substitutions and make sure Text Replacement has a tick. While you’re there, Show Substitutions lists every switch for that app in one small window.

If there’s no Substitutions menu at all, the app draws its own text fields. Skip to step 5.

3. Check the shortcut itself

Open System Settings → Keyboard and click Text Replacements…. Then check three things:

• Spelling. The shortcut has to match exactly what you type. A stray space at the end is easy to miss.
• No spaces inside. A shortcut is one word. my addr won’t work; myaddr will.
• Not a real word. If your shortcut is a word you also type for real, like addr or sig, you’ll get the replacement when you don’t want it. Start shortcuts with a character you never type, like ; or @@.

4. Finish the word

A Text Replacement doesn’t fire when you finish typing the shortcut. It fires on the space or punctuation after it. Type omw and stop, and nothing happens. Type omw and a space, and it expands.

In some apps it shows as a suggestion instead: a small bubble under the word that you accept with Space, or dismiss with Esc. If you press Esc out of habit, you’ve turned it down.

5. The apps that never expand them

Text Replacements are part of Apple’s text system, so they only work in text fields that use it. Plenty of popular apps draw their own:

• Microsoft Word, Excel and PowerPoint. They use Office’s own AutoCorrect instead. Add the same shortcut in Word under Tools → AutoCorrect.
• Google Docs. It has its own list under Tools → Preferences → Substitutions.
• Electron apps, such as Slack, Discord, VS Code, Notion and Obsidian. Some pick up the Mac’s spelling, but your replacements usually don’t expand.
• Terminals: Terminal, iTerm2, Ghostty and the rest.
• Web apps with their own editors, like many chat and email tools in the browser. A plain text box on a web page often works in Safari, but a fancy editor usually doesn’t.

There’s no setting on the Mac that changes this. You either add the shortcut again inside the app (Word, Google Docs) or use a text expander that types into any app.

6. When they don’t reach your iPhone

Text Replacements sync through iCloud, and when they don’t arrive it’s usually one of these:

• Both devices must be signed in to the same Apple Account, with iCloud on.
• Syncing can take a while. Add one test replacement on the Mac, and give it time before you change anything else.
• If one device never gets them, signing out of iCloud and back in on that device is the usual last resort. Make sure your other iCloud data is synced first.

7. See every replacement from Terminal

The Settings list is fine for ten replacements and painful for fifty. Your Mac keeps them in a small database you can read:

sqlite3 ~/Library/KeyboardServices/TextReplacements.db \
  "select ZSHORTCUT, ZPHRASE from ZTEXTREPLACEMENTENTRY where ZWASDELETED = 0;"

It prints one replacement per line, shortcut first:

;addr|221B Baker Street, London NW1 6XE
omw|On my way!
;sig|Thanks, Anmol

Mine listed 10 (those three are examples, not mine). Change the end to select count(*) from ZTEXTREPLACEMENTENTRY where ZWASDELETED = 0; to get only the number. It’s a quick way to spot a typo in a shortcut, or a duplicate where two shortcuts fight. Only read it: changes made here don’t sync, so edit replacements in System Settings.

To back them up, select them all in the Text Replacements window (⌘A) and drag them to the desktop. You get a .plist file you can drag back in on any Mac.

When Text Replacements aren’t enough

If most of your typing happens in Slack, a terminal or Word, step 5 is the wall you keep hitting. That’s where a text expander takes over, because it watches the keyboard instead of relying on each app’s text system.

Full disclosure, I built one: Snipora. It reads your Text Replacements the first time it opens and expands them in every app, Electron apps and terminals included, and Esc undoes an expansion you didn’t want. It’s free for 15 snippets; the lifetime licence is $8.99 for the first 50 buyers, then $39.99. If your replacements only need to work in Apple’s apps, you don’t need it: the built-in ones are free and sync to your iPhone.

Back to the built-in ones.

One habit that prevents most of this

Start every shortcut with the same character. I use ;: ;addr, ;sig, ;mtg. You’ll never type it by accident, you can see all of them at a glance in the Settings list, and when one stops working, you know it’s the app and not a clash with a real word.

FAQ

Where are Text Replacements on a Mac?

System Settings → Keyboard → Text Replacements…. Click + to add one.

Why does my text replacement work in Notes but not in Word?

Word uses Office’s own AutoCorrect, not the Mac’s list. Add the shortcut under Tools → AutoCorrect in Word.

Why don’t text replacements work in Slack or VS Code?

They’re Electron apps that draw their own text fields, so Apple’s text system never sees what you type. Nothing in System Settings changes that.

Can a text replacement contain today’s date?

No. Text Replacements are fixed text. A Shortcuts keyboard shortcut or a text expander can type the date.

Can a text replacement have more than one line?

Yes, but you can’t type a line break in the Settings field. Write the text in TextEdit, copy it, and paste it into the Replace With field.

The bottom line

Test in TextEdit first. If it works there, the app is the problem: switch it on under Edit → Substitutions, or add the shortcut to the app’s own list. If it doesn’t, check the spelling, and remember the space at the end.

Which app do your text replacements fail in most? Tell me in the comments.

I’m Anmol. I build Mac apps and write about Mac productivity. Follow me on X at @anmolsethi_dev.