How to use wp_handle_upload() to upload files in WordPress

Most of the time in theme options or in plugins we give option to upload files. Wordpress wp_handle_upload() function makes it easy to upload the files.

Most times in theme option or in plugins we give option to upload files. WordPress wp_handle_upload() function makes it easy to upload these files. Function wp_handle_upload() has proper error handling and uploads file to current month upload directory.

WordPress uses this function to upload media, upload import file, upload header background and upload background image. In this post I will show how to use wp_handle_upload().

php code:

$overrides = array( 'test_form' => false);
$file=wp_handle_upload($_FILES['rt_file'], $overrides);

wp_handle_upload() accepts two parameters. $_FILES[‘rt_file’] is single element of $_FILES and the second parameter is array to override default file upload options. Parameter $overrides is optional but always set $overrides with value test_form=false else it will return form submission error.

On success wp_handle_upload() returns an associative array of file attributes. The returned array has the absolute path of an uploaded file, URL of an uploaded file & type of uploaded file.

On failure wp_handle_upload() returns array which has error message.

We can use our own error handling function by passing function name in $overrides[‘upload_error_handler’] as shown below:

$overrides = array( 'test_form' => false,'upload_error_handler' =>rt_handle_upload_error );

‘rt_handle_upload_error’ is our defined function to handle upload error.

There is no need to override default wp_handle_upload options except test_form.

You can add more mime types for upload using upload_mimes filter.

You will find wp_handle_upload() in wp-admin/includes/file.php.

Hope it helps handling uploading files in WordPress. 🙂 Feel free to share your views or queries through your comments.


Prasad October 11, 2010

This has certainly given me additional knowledge since i was unaware about the second parameter of wp_handle_upload() and how vital it is. Thanks for sharing…!

Umesh October 14, 2010

Now you can easily use wp_handle_upload() in plugins and theme options.

Wannes December 9, 2010

Yes, that overrides parameter is a vital tip. It’s weird how widely undocumented this is.

Leo Plaw January 4, 2011

Yes, I agree Wannes that there is little to no online documentation for overrides, however, after stepping through the WordPress code, it is all very clearly commented. Somebody needs to take the comments from
/wp-admin/includes/file.php wp_handle_upload()
and write it up on the Codex.

Leo Plaw January 4, 2011

You should not be using: ‘test_form’ => false

You are disabling all checking on file uploads, which means somebody could upload something like a .exe file and actually do some bad things.

You should be using: ‘action’ => ‘editpost’.

If you need then to upload any files which are not of the mime type allowed by WordPress you can then use the filter ‘upload_mimes’ to add any of the necessary files types you want to allow.

add_filter(‘upload_mimes’, ‘my_upload_mimes’);

Umesh Nevase January 4, 2011

If we not kept ‘test_form’ => false the wp_handle_upload() not works. If you see wordpress custom background image upload functionality or custom header upload functionality, wordpress uses ‘test_form’ => false. I know ‘upload_mimes’ filter is used to add more file types other than wordpress defined file types.

Leo Plaw January 4, 2011

‘action’ => ‘editpost’ plus with changing the mime type (I wanted to upload audio files) worked for me. As I said using ‘test_form’ => false is a bad thing, because it means people can abuse your server. There is are very good reasons the WordPress programmers added the file checking. You need to examine your code if it is not working with file checking. A good starting point to help you is to read through the comments in /wp-admin/includes/file.php wp_handle_upload(). It helped me. 8)

Thomas January 6, 2011


Thank you for this !
I’ve been searching that for days, I just need my members able to upload images in a form to finish my website, i’ll try with that

Umesh Nevase January 7, 2011

Hope that it will solve your problem.

John February 8, 2011

I tried this and got the following error-

Fatal error: Call to undefined function wp_handle_upload()

It seems there is something missing. Appreciate your help.

Umesh Nevase February 14, 2011

You got this problem if you are using wp_handle_upload() in plugin. Include wp-admin/includes/file.php in your plugin.

billy March 2, 2011

What exactly do you mean by this and how does one go about correctly “including” the file.

Umesh Nevase March 5, 2011

If you are using wp_handle_upload() in plugin, just add this 2 lines in your plugin

marc January 26, 2013

Hi John, I am having same issue, did you resolve it?
I appreciate your help, or anyone here

[email protected] January 30, 2013

Hi Marc,
Just include file.php before using wp_handle_upload
require_once ( ABSPATH . ‘wp-admin/includes/file.php’ );

jonah February 28, 2011

i’m creating a memorial site where i want anyone to be able to upload photos. i don’t want to give out accounts to everyone — i don’t want them them all to have to understand the WP interface. the media area is confusing. i just want regular users to be able to upload files, but utilize wordpress’ file checking, and saving of the various image sizes. is this doable? is it truly dangerous? i was hoping to just include wp-admin/includes/file.php in a theme template, but am getting errors. am i crazy?

as of now, the posts being created from this front-end interface are all initially set as pending, since it’s a memorial and we can’t have spam, or offensive content.

i’d appreciate your help.


Umesh Nevase March 5, 2011

Jonah, If you are using wp_handle_upload in theme, then no need to include

Claudio Monzoni May 14, 2011


Is there are tutorials online for this.. i mean step by step and download file 😛 , I buy a theme but dont have the upñoad images option to the user can submit their own post with images and i want try to add it

GeeksFolder September 30, 2011

Hey thanks for your tutorial.

Is there any way I can upload files in a different location
instead of the current month folder?

Thanks in advance!

[email protected] September 30, 2011

GeeksFolder, Thanks for your comment. I have checked for options to upload files in different location but I did not get any option.

T W July 5, 2012

First place I could find a straight answer. Thank you very much for this.

Ankit Gade May 3, 2013

Thanks a lot for brief description ..It helped me 🙂