Installation Failed: Could Not Copy File (and Could Not Remove the Old Plugin)

Why it happens

• The disk, or the hosting account's storage quota, filled up while WordPress was writing the new files. The write stops halfway through one file.
• The folder the files go into is on a different disk or quota from wp-content/upgrade. WordPress then has to copy file by file instead of moving the folder, so it can run out of room even when the disk with upgrade has plenty.
• The plugins folder belongs to another user, such as root, while the plugin's own folder belongs to the PHP user. WordPress can empty the old plugin but cannot delete its folder, so "Could not remove the old plugin." appears.
• The plugin's own folder and files belong to another user. This shows as a longer message, "The update cannot be installed because some files could not be copied."

How to fix it

Try the fixes in this order. Each one is independent: stop as soon as the error is gone.

WordPress writes a plugin in several steps, and this message does not say which one failed. The same words, "Could not copy file.", come from two different steps, and a third step says "Could not remove the old plugin." The first thing to do is find the step. Then fix what that step needs: free room on the disk, or the right owner on a folder. On an update, check afterwards that the old plugin is still there.

What you see#

On Plugins → Add Plugin, Install Now shows the message under the plugin card:

An update from Plugins shows the same words with "Update failed:" in front:

And when the old folder cannot be deleted:

The steps and where each message comes from#

Here is how to tell them apart. I produced each one on a WordPress 7.1.4 test site running PHP 8.3.

The paths do not show in the browser. WP-CLI prints them. Here is the unpack step failing for a new install:

wp plugin install awc-lab-hours-1.1.0.zip

Unpacking the package...Warning: Could not copy file. "awc-lab-hours/data.bin"Warning: The '/var/www/html/awc-lab-hours-1.1.0.zip' plugin could not be found.Error: No plugins installed.

And the copy step failing on an update:

Enabling Maintenance mode...Downloading update from http://localhost/awc-lab-hours-1.1.0.zip...Unpacking the update...Installing the latest version...Removing the old version of the plugin...Warning: Could not copy file. "/var/www/html/wp-content/plugins/awc-lab-hours/data.bin"Plugin update failed.Disabling Maintenance mode...Error: No plugins updated (1 failed).

Why the copy step fails when the disk is not the same#

When WordPress installs from its working folder, it first tries to rename the folder into place. That is instant and needs no space. A rename cannot move a folder from one disk to another, so then WordPress falls back to copying every file with copy_dir(). PHP says so:

PHP Warning:  rename(/tmp/exa,/dev/shm/exb): Invalid cross-device link

So when plugins is on a different disk or quota from wp-content/upgrade, each install writes the new plugin there for real, one file at a time. If that disk is full, the file in progress fails and the error names it. I set this up on purpose in my lab: a small memory disk for plugins, and the normal disk for upgrade. Many sites do not do this, and on them the rename works and a full disk shows up in the unpack step instead.

What is left behind after a failure#

Do not assume the site is clean. I checked the folders after each failure.

A failed install leaves a part-written plugin. After the Classic Editor install above, wp-content/plugins/classic-editor held a js folder and a scripts folder, and post.min.js was cut off at 4096 bytes. Trying again said "Destination folder already exists." Deleting that folder, with space freed, made the install work.

A failed update after the copy step puts the old plugin back. Since WordPress 6.3, an update moves the old plugin into wp-content/upgrade-temp-backup before it removes anything, and moves it back on failure. After the failed copy above, the plugin was back on version 1.0.0 and active, and the backup folder was empty. When I freed the space and ran the update again, it worked. The Make Core merge proposal describes the manual update safeguard as present since 6.3.

A failed remove can leave the plugin empty. This is the dangerous case. With plugins owned by root and the plugin folder owned by www-data, the update printed "Could not remove the old plugin." and the plugin was gone from the list. The backup step could copy the old files out and delete their contents, but it could not delete the folder itself. The restore step then could not delete that folder either, so it did not put the files back, and WordPress deleted the backup. I logged the folders at the end of the request:

before restore                 backup:3 items plugin dir:0 itemsafter restore, before delete   backup:3 items plugin dir:0 itemsafter delete                   backup:missing plugin dir:0 items

The plugin folder was empty and the backup was gone. The same thing happened when I clicked Update in the browser. Reinstalling fixed it, as in the fix list above. I only saw this when the plugin's folder is owned by PHP's user and its parent folder is not. That is why the owner fix comes before any retry.

Edge cases I tested#

A root-owned file inside the plugin folder does not block an update. Many guides say it does. I put a file owned by root inside a plugin folder that www-data owned, and the update printed "Plugin updated successfully." WordPress moves the whole old folder away in one step, so it never has to delete that one file separately. The delete of the backup folder works too, because the folder is the one PHP owns.

A root-owned plugin folder gives a different message. With the folder and all its files owned by root, WordPress checked the files before it deleted anything and printed "The update cannot be installed because some files could not be copied. This is usually due to inconsistent file permissions." The plugin stayed on 1.0.0 and active. That is the safe outcome. The unpacked new version stayed behind in wp-content/upgrade, so look there if the folder grows.

"Could not copy files. You may have run out of disk space." This is a separate message. The code in unzip_file() only checks free space when it runs from WP-Cron, for background updates, and it needs 2.1 times the unpacked size. I did not get a real background update to show it. To check the code, I defined DOING_CRON in WP-CLI and called unzip_file() on a zip that holds 8 GB of zeros. It returned the error disk_full_unzip_file and wrote nothing. Do not confuse it with "Could not copy file." from a browser click: that message has no space check, and it appears only once a write has failed.

A WP-CLI update is not the same as an admin click. Every terminal result above comes from WP-CLI as www-data. I used the browser for the three screenshots, and the outcome for the copy and remove cases matched. WP-CLI forces direct file writes, so on a site that shows the FTP form in the browser, see the filesystem credentials page.

If it keeps happening#

An update that fails on the same file each time points to a full disk or to a folder on a separate small disk. Compare the three folders in the first fix. An update that stops with a different message is probably a different problem: see could not create directory for the step before this one, and another update is currently in progress if WordPress says an update is already running.

For a safe routine before you update plugins, read how to update plugins safely.