Better Upload Filename Sanitization in WordPress

October 28th, 2015

If you are like me, you feel like there is a lot to be desired for how uploaded filenames look in WordPress. Don’t get me wrong, it does a decent job in terms of making them web-safe (sometimes?), but for actually making a standardized, consistent structure across everything – not so much. Here’s something I’ve been throwing in my theme’s functions.php as of late. Written to be easily editable.

// Sanitize file upload filenames
function sanitize_file_name_chars($filename) {

  $sanitized_filename = remove_accents($filename); // Convert to ASCII

  // Standard replacements
  $invalid = array(
    ' ' => '-',
    '%20' => '-',
    '_' => '-'
  $sanitized_filename = str_replace(array_keys($invalid), array_values($invalid), $sanitized_filename);

  $sanitized_filename = preg_replace('/[^A-Za-z0-9-\. ]/', '', $sanitized_filename); // Remove all non-alphanumeric except .
  $sanitized_filename = preg_replace('/\.(?=.*\.)/', '', $sanitized_filename); // Remove all but last .
  $sanitized_filename = preg_replace('/-+/', '-', $sanitized_filename); // Replace any more than one - in a row
  $sanitized_filename = str_replace('-.', '.', $sanitized_filename); // Remove last - if at the end
  $sanitized_filename = strtolower($sanitized_filename); // Lowercase

  return $sanitized_filename;

add_filter('sanitize_file_name', 'sanitize_file_name_chars', 10);

So how then does the WordPress default fair against the custom solution proposed above? Here’s the results on some examples:

File: ~Super Important Document~.pdf
Default WordPress: Super-Important-Document.pdf
Custom Solution: super-important-document.pdf

File: ÐÕçument full of $$$.pdf
Default WordPress: ÐÕçument-full-of-.pdf
Custom Solution: document-full-of.pdf

File: Really%20Ugly%20Filename-_-That_-_Is_Too Common…..png
Default WordPress: Really-Ugly-Filename-_-That_-_Is_Too-Common…..png
Custom Solution: really-ugly-filename-that-is-too-common.png

This entry was posted in Blog and tagged , .

7 Responses to Better Upload Filename Sanitization in WordPress

April 9th, 2016
zeze says:

Wow! In the end I got a website from where I know how to actually get helpful
facts concerning my study and knowledge.

August 23rd, 2016
Sean P Sullivan says:


Still, I added this to my functions.php but the filename still gets put through the default sanitize_file_name() function first. Wierd.

October 19th, 2016
junvin says:

thank so much !!!
great job

February 9th, 2017
Robert says:

Is there any difference to thak – I used:


add_filter( ‘sanitize_file_name’, ‘remove_accents’, 10, 1 );
add_filter( ‘sanitize_file_name_chars’, ‘apgbr_sanitize_file_name_chars’, 10, 2 );

if ( ! function_exists( ‘apgbr_sanitize_file_name_chars’ ) ) {
function apgbr_sanitize_file_name_chars( $special_chars = array() ) {
$special_chars = array_merge( array( ‘’’, ‘‘’, ‘“’, ‘”’, ‘«’, ‘»’, ‘‹’, ‘›’, ‘—’, ‘æ’, ‘œ’, ‘€’ ), $special_chars );

return $special_chars;


I get actually da same resault: clean filenames.

June 29th, 2017
Vinicius says:


filenames like this:

Really%20Ugly%20Filename-_-That_-_Is_Too Common…..png

are being converted like that:


You can notice the “20” was not replaced by the “-“.

What is wrong with your code?

July 28th, 2017
Horizon says:

Thank’s it will be intagrated in all my project since it avoid a ton of problems.

Even if images with special caracters may work on some server if you use an image as background for whatever reasons it will not work in some browser.

June 18th, 2018
Marco says:

Hi, thanks for your tricks!
Have you a solution to sanitize and clean all existing media filenames?
Do you know a plugin for this function?

Thanks in advance for your reply.


Leave a Reply



This site uses Akismet to reduce spam. Learn how your comment data is processed.