Getting spaces out of filenames on macOS

Final Report (v2) copy.pdf is a perfectly legal filename on macOS. Finder handles it, Preview opens it, nothing complains.

Then you upload it to a web server, or pass it to a script, or put it in a URL, and things start going wrong in ways that are hard to trace back to the name.

Where spaces actually break

The shell. cat Final Report.pdf is two arguments, not one. Every space needs escaping or quoting, and the failure mode is often not an error but the wrong thing happening quietly — a command that processes the wrong file rather than refusing.

URLs. A space becomes %20. Your file is reachable but every link to it is ugly, and some older systems mangle the encoding somewhere along the chain.

Scripts and build tools. Anything that iterates over filenames without careful quoting will split on spaces. This is one of the most common bugs in hand-written shell scripts.

Cross-platform transfer. Windows and Linux tolerate spaces, but the combination of spaces and other characters — colons, question marks, asterisks — is where cross-platform breakage becomes reliable.

Version control. Git handles spaces, but diffs and command-line operations get noisier.

For files that only ever live in Finder and get opened by double-clicking, spaces are genuinely fine. The rule is about where the file is going.

What to replace them with

Hyphens for anything web-facing. final-report-v2.pdf. Search engines treat hyphens as word separators; they read that as three words. Underscores they historically treated as joining characters.

Underscores for code and data files, where they are conventional and read as part of an identifier.

camelCase or PascalCase if you prefer, though it reads worse at a glance in a long file list.

Pick one and use it consistently. A folder with three conventions in it is worse than a folder with spaces.

The other characters worth removing at the same time

While you are cleaning names, these cause more trouble than spaces:

• : / \ — path separators on one system or another. A colon in a filename is a genuinely bad idea on a Mac for historical reasons.
• ? * " < > | — wildcards and redirects in shells, illegal on Windows.
• # and % — special in URLs. A # truncates the link at that point.
• & — splits commands in shells.
• Leading dots make the file hidden.
• Trailing spaces or dots are invisible and cause "file not found" on Windows.
• Non-ASCII characters. Ş, ğ, ü, é are fine on modern systems but can arrive mangled through older upload pipelines, FTP, or a badly configured server. For anything web-facing, transliterate: şirket-raporu rather than şirket raporu, and ideally sirket-raporu.

Also worth collapsing: repeated separators (report--final.pdf), and the copy, copy 2, final, final-final sediment that accumulates on a project.

Lowercase or not

For web-facing files, lowercase everything. macOS filesystems are usually case-insensitive, Linux servers are not, and the failure — Logo.PNG uploaded, logo.png linked — produces a broken image that works fine on your machine.

For local working files it does not matter much.

Before you run it on a project folder

Two specific risks with this particular operation:

Broken references. If the files are linked from an HTML page, a design document, a spreadsheet or a script, renaming them breaks every link. Search the project for references first, or rename and fix together.

Collisions. My Report.pdf and My-Report.pdf both become my-report.pdf. Two files, one name. Any tool that resolves this silently by appending a number has quietly changed which file is which.

And take a copy first. This is a cheap operation to undo only if you can see what it did.

Doing this with RenameDeck

This is a two-rule recipe: replace spaces with hyphens, then lowercase. RenameDeck stacks rules like that into a single pass, with literal, wildcard or regular-expression filters if you only want it applied to some files.

The part that matters here is the preview. You see the complete result list before anything is renamed, so the collision between My Report.pdf and My-Report.pdf shows up as a detected conflict rather than as a surprise afterwards. It detects invalid names and never overwrites an existing file.

Save the recipe and the next batch of files is one click. For a folder you drop web assets into constantly, assign a frozen recipe to it and the cleaning happens on arrival. Journaled transactions mean an eligible batch can be undone properly.

The app is sandboxed with no network entitlement, so nothing about your files leaves the Mac. It requires macOS 14 or later.