Upload Files to Media Library Programmatically
When you upload files to your website using media uploader in admin area, WordPress usually handles everything for you. So all the uploaded files automatically appear in WordPress media library and after that can be easily managed, inserted to posts etc.
But when you create some custom functionality, or maybe forms on your website front-end, you should handle it by yourself. And in this tutorial I will show you how.

In this tutorial we are going to take a look on two scenarios:
- When upload images from url (not only images of course),
- When upload files using a form.
Upload Images from URL Programmatically
Let’s begin with an image anywhere on the internet. Assuming that we have its URL, and now it is stored in the variable $image_url
. How to add it to media library right now?
/**
* Upload image from URL programmatically
*
* @author Misha Rudrastyh
* @link https://rudrastyh.com/wordpress/how-to-add-images-to-media-library-from-uploaded-files-programmatically.html#upload-image-from-url
*/
function rudr_upload_file_by_url( $image_url ) {
// it allows us to use download_url() and wp_handle_sideload() functions
require_once( ABSPATH . 'wp-admin/includes/file.php' );
// download to temp dir
$temp_file = download_url( $image_url );
if( is_wp_error( $temp_file ) ) {
return false;
}
// move the temp file into the uploads directory
$file = array(
'name' => basename( $image_url ),
'type' => mime_content_type( $temp_file ),
'tmp_name' => $temp_file,
'size' => filesize( $temp_file ),
);
$sideload = wp_handle_sideload(
$file,
array(
'test_form' => false // no needs to check 'action' parameter
)
);
if( ! empty( $sideload[ 'error' ] ) ) {
// you may return error message if you want
return false;
}
// it is time to add our uploaded image into WordPress media library
$attachment_id = wp_insert_attachment(
array(
'guid' => $sideload[ 'url' ],
'post_mime_type' => $sideload[ 'type' ],
'post_title' => basename( $sideload[ 'file' ] ),
'post_content' => '',
'post_status' => 'inherit',
),
$sideload[ 'file' ]
);
if( is_wp_error( $attachment_id ) || ! $attachment_id ) {
return false;
}
// update medatata, regenerate image sizes
require_once( ABSPATH . 'wp-admin/includes/image.php' );
wp_update_attachment_metadata(
$attachment_id,
wp_generate_attachment_metadata( $attachment_id, $sideload[ 'file' ] )
);
return $attachment_id;
}
Upload Files in PHP Using Forms
This part of the tutorial is kind of similar, the only difference is that we are not going to get the file from a remote URL, but upload it ourselves.
1. HTML form
As an example we can upload user profile pictures.
<form action="<?php echo get_stylesheet_directory_uri() ?>/process_upload.php" method="post" enctype="multipart/form-data">
Your Photo: <input type="file" name="profile_picture" />
<input type="submit" name="submit" value="Submit" />
</form>
What is recommended to remember here?
- I placed the PHP file
process_upload.php
into my theme directory, if you would like to move it to the other location, do not forget to make changes in the following codes as well. If you’re interested in AJAX file uploads, check this tutorial please. - The form must have
enctype="multipart/form-data"
attribute. Many forget about it.
You can also create a shortcode for this form, just insert this to the functions.php
:
add_shortcode( 'misha_uploader', 'misha_uploader_callback' );
function misha_uploader_callback(){
return '<form action="' . get_stylesheet_directory_uri() . '/process_upload.php" method="post" enctype="multipart/form-data">
Your Photo: <input type="file" name="profile_picture" />
<input type="submit" name="submit" value="Submit" />
</form>';
}
Now you can use just [misha_uploader]
in the editor.
2. Process the uploaded file in PHP and add it to media library programmatically
Below is process_upload.php
file that I decided to create in my current theme directory.
<?php
// WordPress environmet
require( dirname(__FILE__) . '/../../../wp-load.php' );
// it allows us to use wp_handle_upload() function
require_once( ABSPATH . 'wp-admin/includes/file.php' );
// you can add some kind of validation here
if( empty( $_FILES[ 'profile_picture' ] ) ) {
wp_die( 'No files selected.' );
}
$upload = wp_handle_upload(
$_FILES[ 'profile_picture' ],
array( 'test_form' => false )
);
if( ! empty( $upload[ 'error' ] ) ) {
wp_die( $upload[ 'error' ] );
}
// it is time to add our uploaded image into WordPress media library
$attachment_id = wp_insert_attachment(
array(
'guid' => $upload[ 'url' ],
'post_mime_type' => $upload[ 'type' ],
'post_title' => basename( $upload[ 'file' ] ),
'post_content' => '',
'post_status' => 'inherit',
),
$upload[ 'file' ]
);
if( is_wp_error( $attachment_id ) || ! $attachment_id ) {
wp_die( 'Upload error.' );
}
// update medatata, regenerate image sizes
require_once( ABSPATH . 'wp-admin/includes/image.php' );
wp_update_attachment_metadata(
$attachment_id,
wp_generate_attachment_metadata( $attachment_id, $upload[ 'file' ] )
);
// just redirect to the uploaded file
wp_safe_redirect( $upload[ 'url' ] );
exit;
// or you can use update_user_meta() if you're going ot use it as a profile picture
Optionally we can set the third parameter of the wp_insert_attachment()
as a parent post ID, and set the featured image of this post with set_post_thumbnail()
.

Misha Rudrastyh
Hey guys and welcome to my website. For more than 10 years I've been doing my best to share with you some superb WordPress guides and tips for free.
Need some developer help? Contact me
You saved my life! thank you thank you thank you so much!!
I’m happy to help, you’re welcome! 🙃
How to upload multiple images?
¡Hola!
Add “[]” to the name of the input tag:
<input type="file" name="profilepicture[]" />
Very good code, thank you!
You helped me with my graduation.
I have the following error: “Call to undefined function mime_content_type()”
Hey Oliver,
What is your PHP version?
¡Hola Misha! Hi! Gracias, Thank you.
Sorry to bother you, in case you could guide me. I am a photographer and I would like to add many photos to my WP from home.
I have created a function that generates images of different size to the original that my theme needs (66×66, 200×133 …). Thus the weight of the images is much lower than those automatically generated by WP.
To streamline my workflow in WP, I thought about creating a function to upload the images to / wp-content / uploads / 2018/07 via php (now what I do is copy them directly into the folder of the WP installation).
I have also generated a query to the DB to add the necessary information to wp_post and wp_postmeta for each image.
I can use the uploaded image with no problem, I can add it to an entry or page and it looks correctly, both in the WP editor and later on the web.
However, in the WP media gallery the image is not shown to me. It’s like it does not associate the data in the database with the image that I copied in / uploads / 2018/07.
I have noticed and there is no other reference to the images apart from the ones I have already entered in the MYSQL query.
Maybe what I want to do is complex and I should give up. But I would like to at least know where the error may be.
Thanks for your time.
A hug from Granada, Spain.
Hi Alejandro 🙃
Not sure how your function looks like, but I think the code below should help you.
P.S. Never give up 💪
Thank you very much Misha!
Unfortunately I do not know how to implement what you have indicated :(
I do not know how to use the WP functions in my code.
I will try to explain what I have done.
I created a .php out of WP with a connection to a BD (out of WP). I have created a function that runs through a directory with photos to be able to visualize them and move them by assigning an order to the photos and adding that information to the BD (out of WP).
My idea is to generate the content of a post outside of WP, including directly on the WordPress DB the information that I add in my BD (out of WP).
When I read your answer I thought, maybe if I move my .php to the WP installation directory, maybe it will work. But I have to add the WP functions to my .php.
I did it by adding require_once (‘../ wp-load.php’), but if I see my .php in the browser, I get a 404 error code with the appearance of my WP theme.
I get lost here, I have no idea how I could see my page created in .php without the theme, being able to use the functions of WP, for me to be able to test the code that you have given me.
Thank you very much for everything Misha, you have been very kind. I’m sorry I can not put into practice the code you’ve given me, I’m sorry.
A hug.
Oh!
I have discovered
define('WP_USE_THEMES', false);
Sorry, at this moment I’m not 100% sure what you’re doing…
Ok, you have a PHP script, you’ve placed it in your WP directory. It is OK, but if it lays directly in WP directory, not in a subfolder, here how to include WP Environment correctly:
require_once ( dirname(__FILE__) . '/wp-load.php' );
Once you included this file, you can place the code I gave you above in it too.
Hi Misha, thank you very much for your time. You’re very kind. “Un tipo cojonudo”. A great guy we say in Spain.
I have tested your code and it works great. What I’m going to do is try to implement it in my code, to see if I’m capable.
Let’s see if I can explain what I want to do. I will be putting a numbered list to see if I explain myself better.
1. I work on localhost with wamp.
2. I have a folder with photos outside of the WordPress installation directory.
3. These photos are the ones I want to add to WordPress. Upload them to the uploads directory.
4. I create a function that runs through the directory of the photos. Could I avoid the form submit? I think that this is the point at which I am not able to implement your code with mine. I do not know exactly how to do it. (Right now I am working on this point).
Thank you very much. Thank you very much.
A hug.
Yes, I understand you correctly.
If you need help with the code, I can write it for you, just contact me.
You are a champion!
This is awesome! It is helping me to finish up a custom plugin I am developing. I have one question: how would I go about displaying the uploaded image using a shortcode?
Hi Melissa,
I need more details.
Please could you help me back giving the snippet for the uploading multiple files from frontend with one fixed featured image and the rest other pictures as in a gallery in WordPress.
Hi,
sure,
If you would like to upload multiple files, you can just add
multiple
attribute to your input field and do not forget to add[]
to the field name.<input type="file" name="profilepicture[]" multiple />
After that you have to process
$_FILES['profilepicture']
as an array.To attach images to a post, add its ID as a third parameter of
wp_insert_attachment()
function.To set an image as a featured image, use this:
set_post_thumbnail( $post_id, $attachment_id );
You are a champion!
how to save uploaded image in custom post type post in custom field?
Hi,
Would you like to save the image ID or url ?
actually i need that uploaded image should be upload in media and custom post type post in custom field
Perfect! But a question, how do I delete the image from the database as soon as the user sends another one?
wp_delete_attachment()
🙃Hey buddy, thank you so much!
Hi
First of all great function I love it!
But I need to have a extra function here instead of
I need a function to say if (empty) the $upload_id = $variable
Will be using it with update_post_meta and not instert_post can you give me a code or point me in the right direction please.
Hi Wilhelm,
So, you would like to have some kind of placeholder here, right?
Thank you so much :)))))
thanks a lot man
i love you
I want to leave a comment because I learn from this. This code save a lot of time and efforts. Thank you so much.
Great stuff, as always, thank you Misha!
You’re welcome! 🙏🏼 😌
Thank you X 1000000000000000
Muchas gracias misha desde argentina
Merci infiniment ;) !!!
Hi,
I’m try upload files mp3 but I have response error:
“http_request_failed”: [“A valid URL was not provided.”]
Is there any chance that your file is on localhost or blocked with http auth?
if i try to upload a “jpg” image, it creates the tmp file like /var/tmp/15524-muF7NB.tmp and wp_handle_sideload prints error “Sorry, you are not allowed to upload this file type.”. Whats wrong with my file input?