$files->rename() method

Rename a file or directory and update permissions

Note that this method will fail if pathname given by $newName argument already exists.

Available since version 3.0.118.


// basic usage
$bool = $files->rename(string $oldName, string $newName);

// usage with all arguments
$bool = $files->rename(string $oldName, string $newName, $options = []);



Old pathname, must be full disk path.


New pathname, must be full disk path OR can be basename to assume same path as $oldName.

options (optional)array, bool, string

Options array to modify behavior or substitute limitPath (bool or string) option here.

  • limitPath (bool|string|array): Limit renames to within this path, or boolean TRUE for site/assets, or FALSE to disable (default=false).
  • throw (bool): Throw WireException with verbose details on error? (default=false)
  • chmod (bool): Adjust permissions to be consistent with $config after rename? (default=true)
  • copy (bool): Use copy-then-delete method rather than a file system rename. (default=false) 3.0.178+
  • retry (bool): Retry with 'copy' method if regular rename files, applies only if copy option is false. (default=true) 3.0.178+
  • If given a bool or string for $options the limitPath option is assumed.

Return value


True on success, false on fail (or WireException if throw option specified).


Method can throw exceptions on error:

  • WireException - If error occurs and $throw argument was true.

$files methods and properties

API reference based on ProcessWire core version 3.0.228

Latest news

  • ProcessWire Weekly #498
    The 498th issue of ProcessWire Weekly brings in all the latest news from the ProcessWire community. Modules, sites, and more. Read on!
    Weekly.pw / 25 November 2023
  • Using date range fields in ProcessWire
    This week we'll take a detailed look at the newest addition to the ProFields set of modules: the Date Range Fieldtype and Inputfield.
    Blog / 24 November 2023
  • Subscribe to weekly ProcessWire news

“We chose ProcessWire because of its excellent architecture, modular extensibility and the internal API. The CMS offers the necessary flexibility and performance for such a complex website like superbude.de. ProcessWire offers options that are only available for larger systems, such as Drupal, and allows a much slimmer development process.” —xport communication GmbH