`sed -i` on Mac Is a Trap If You Copy GNU Examples Without Thinking About Portability

Why this bug keeps happening: developers search for a sed -i example, paste a GNU/Linux answer into macOS, and then assume sed is broken when the real issue is platform behavior.

Why sed still matters

For quick file edits, config rewrites, build scripts, and one-line replacements, sed remains one of the most useful shell tools around. The GNU manual describes it as a stream editor, which is accurate, but developers often meet it first through in-place edits to real files.

A typical Linux example looks like:

sed -i 's/localhost/127.0.0.1/' config.txt

On macOS, that exact command often causes frustration because BSD sed handles -i differently.

The macOS difference people trip over

On macOS, in-place editing typically expects a backup extension argument after -i, even if that extension is empty.

That means a more portable macOS-friendly form is:

sed -i '' 's/localhost/127.0.0.1/' config.txt

The empty string means “edit in place and do not keep a backup file.” If you want backups:

sed -i '.bak' 's/localhost/127.0.0.1/' config.txt

Now you will end up with a backup like config.txt.bak.

Why this matters in scripts

The annoying part is not the one-liner itself. It is when shell scripts work on Linux CI but fail on a MacBook, or vice versa. Then teams waste time arguing about quoting when the true issue is tool flavor.

This is why platform-aware scripting matters. A command that “worked on Stack Overflow” is not the same as a command that is portable across your real environments.

A better habit for risky edits

If the replacement is important, either use a backup extension or preview the change first without -i.

Preview:

sed 's/localhost/127.0.0.1/' config.txt

Then, if the output looks right, run the in-place version.

This preview step matters because sed is obedient, not forgiving. A broad pattern can rewrite far more than you intended.

When sed is the right tool

It is great for:

1. replacing config values in local scripts
2. mass-editing repeated text patterns
3. adjusting generated files in build steps
4. quick transformations without opening an editor

It is not always ideal for highly structured formats where a dedicated parser would be safer. If you are mutating JSON, YAML, or XML heavily, you should at least consider a tool that understands the structure instead of text alone.

Why people blame the wrong thing

Many sed complaints are really one of these:

1. GNU versus BSD behavior mismatch
2. untested in-place edits
3. over-broad replacement patterns
4. using text substitution on structured data without care

Once you separate those causes, the command itself becomes much less mysterious.

The portable mindset that saves teams pain

If a shell script is meant to run on multiple developer machines, write with that fact in mind from the start. Either normalize the environment, document the dependency clearly, or choose command patterns that acknowledge BSD and GNU differences. A script that only works on the author’s laptop is not automation. It is a private convenience that has been mistaken for team infrastructure.

Final recommendation

If you use sed -i on macOS, remember that portability is the real trap, not the idea of in-place editing. Prefer preview-first workflows, know the BSD/GNU difference, and use backup extensions when the change matters. A small amount of discipline saves a lot of shell-script embarrassment.

Sources

• GNU sed manual
• GNU sed manual, single page