Decoding UTF-8 encoded file names

Have you ever downloaded a file only to find its name resembles something your fur kid might type on your keyboard? You know the ones filled with percentage signs and alphanumeric characters like The%20Great%20Gatsby.pdf for English files names or %E8%BF%99%E9%A5%BA%E5%AD%90%E5%A4%AA%E5%A5%BD%E5%90%83%E4%BA%86.png for Chinese file names.

It’s almost as if your fur kid is trying to tell you where it hid the body.

What is going on here?

What you’re witnessing is URL encoding in action—a method where “unsafe” or reserved characters get replaced with a percentage sign (%) followed by two hexadecimal digits.

It’s the digital equivalent of someone translating your name into Morse code when writing it on a coffee cup. Technically correct, but as practical as the barista tapping on the coffee top to announce that your brew is ready.

URL encoding serves a legitimate purpose on the web—ensuring special characters don’t break URLs or confuse servers. But when these encoded names persist in your downloaded files, they’re about as welcome as sand in your swimming costume.

How did this happen to your files?

There are several culprits behind this encoding madness:

Server amnesia: The server forgot to specify the proper file name in the Content-Disposition header, leaving your browser to default to the URL’s encoded path. It’s like a restaurant forgetting to write your name on a takeaway order, so they just use your phone number instead.
Lazy code: The developer who wrote the download system simply forgot to decode the names before serving them up.
Backwards compatibility: Some older operating systems or file systems break into a cold sweat at the sight of Unicode characters, forcing the use of encoded names.

Decoding the code

Fear not! You need not live with files that look like they’ve been through a cryptographic washing machine. Here are some ways to restore order to your digital domain:

For the casual user

The quickest fix is to use online decoders like URL Decode Online. Simply copy your encoded filename, paste it into the decoder, and voilà—legibility returns faster than you can say “percent twenty.”

For the command line connoisseur

If you’re comfortable with a bit of Python (or just want to feel like a hacker in a 90s movie), the urllib.parse.unquote function is your new best friend:

import urllib.parse
encoded_name = "My%20Summer%20Holiday%20Photos%202024.zip"
decoded_name = urllib.parse.unquote(encoded_name)
print(decoded_name)  # Outputs: My Summer Holiday Photos 2024.zip

For the efficiency enthusiast

If you find yourself wrestling with encoded filenames more often than you’d care to admit, it’s time to level up with some proper tools:

PopClip: Your Mac’s Text manipulation wizard

PopClip is that little menu that appears when you select text on your Mac—if you haven’t discovered it yet, you’re missing out on a productivity goldmine. It’s one of the Mac tools that I can’t live without. PopClip is like a contextual Swiss Army knife for text, with a wide selection of extensions for quick actions to speed up your workflow.

The URL Encode extension lets you encode and decode filenames with a selection and a click. You don’t need to do any coding or fiddling. You Just need to download the extension, run it to add it to PopClip, and enable the action.

The caveat here is that you need to buy PopClip. The good news is, you can download it for a free trial to see if you like it. Prefer a free option? The next solution is for you.

Apple Shortcuts: automation for power users

For those who deal with encoded filenames in bulk (you have my sympathies), I’ve created an Apple Shortcut that decodes filenames faster than you can say “why didn’t I think of this sooner?”:

// Apple Shortcuts for Bulk URL decode filenames
// 1. Receive files from Quick Actions input
Receive Files from Quick Actions
// This ensures the shortcut can be run from the share sheet or Files app
// 2. Repeat with each file
Repeat with each item in "Selected Files"
    // 3. Get the current file's name
    Get Name of "Repeat Item"
    Set Variable "Original Name"
    
    // 4. URL decode the filename
    URL Decode "Original Name"
    Set Variable "Decoded Name"
    
// 5. Show completion notification (optional)
Show Notification "URL Decoding Complete" Subtitle "All filenames have been processed"

This little beauty runs as a Quick Action right from your Finder, turning a folder full of digital gibberish into properly named files with a click. I created this for my own specific use case. I know how exactly I will be using it, so I skipped steps that checks if the file name is encoded, and whether the output is properly decoded. You might want to modify it to make it more robust should your workflow require.

The digital decluttering satisfaction

As we increasingly live our lives online, these small digital quality-of-life improvements add up. After all, life’s too short to spend it trying to decipher filenames that look like they’ve been encrypted by an overzealous secret agent.

Spending a bit of time to craft an automation work flow goes a long way to saving you time in the long term.

Do you have any other file management pet peeves or solutions? I’d love to hear about them in the comments below. Or perhaps you’ve found other uses for URL decoding in your digital life? Share your wisdom, and let’s collectively make our digital spaces just a little bit tidier.

Until next time, happy decoding!