rename()

Introduction

The PHP rename() function renames a file or directory — and because a "rename" is really just changing a path, the same function also moves a file or directory to a different location. There is no separate move() function in PHP; you move by renaming to a new path.

This page covers the syntax and parameters of rename(), when to use it (and when not to), the common gotchas around permissions and cross-filesystem moves, and complete runnable examples.

Syntax

rename(string $from, string $to, ?resource $context = null): bool

The function returns true on success and false on failure. On failure it also emits an E_WARNING.

How rename() Behaves

A few rules are worth knowing before you rely on rename():

• It overwrites. If $to already exists and is a regular file, rename() overwrites it (on Unix-like systems, atomically). Check first with file_exists() if you don't want to clobber an existing file.
• The destination directory must already exist. rename() does not create intermediate folders. Use mkdir() first if the target directory is missing.
• Permissions matter. The process running PHP (often the web server user, e.g. www-data) needs write permission on both the source directory and the destination directory — renaming changes directory entries, not just the file itself.
• Cross-filesystem moves can fail. Moving between different mount points or drives is not guaranteed on every platform. When in doubt, copy() the file then unlink() the original.

Examples

Example 1: Renaming a file

<?php
// Create a file to work with so the example is self-contained.
file_put_contents('example.txt', 'hello');

if (rename('example.txt', 'new_example.txt')) {
    echo "File renamed successfully.";
} else {
    echo "Failed to rename the file.";
}

Output:

File renamed successfully.

This renames example.txt to new_example.txt in the same directory.

Example 2: Moving a file into another directory

<?php
file_put_contents('example.txt', 'hello');

// Make sure the destination directory exists first.
if (!is_dir('archive')) {
    mkdir('archive');
}

if (rename('example.txt', 'archive/example.txt')) {
    echo "File moved successfully.";
} else {
    echo "Failed to move the file.";
}

Output:

File moved successfully.

Because the directory part of the path changed, the file is moved into archive/.

Example 3: Safe rename with checks

In real code you usually validate before renaming so you fail with a clear message instead of an unhelpful warning:

<?php
$from = 'report.txt';
$to   = 'reports/2026-report.txt';

if (!file_exists($from)) {
    echo "Source file does not exist.";
} elseif (!is_dir(dirname($to))) {
    echo "Destination directory is missing.";
} elseif (rename($from, $to)) {
    echo "Done.";
} else {
    echo "Rename failed (check permissions).";
}

This guards against the three most common reasons rename() fails: a missing source, a missing destination directory, and insufficient permissions.

rename() vs. copy()

Use rename() when you want to move the data — the original path disappears and nothing is duplicated, which makes it fast and atomic on the same filesystem. Use copy() when you need the original to stay in place, or when you must move across filesystems where rename() may not work. A common cross-filesystem pattern is copy() followed by unlink().

Related Functions

• copy() — duplicate a file.
• unlink() — delete a file.
• file_exists() — check whether a path exists before renaming.
• mkdir() — create the destination directory.
• is_dir() / is_file() — distinguish files from directories.

Conclusion

The rename() function both renames and moves files and directories in PHP. Remember that it overwrites an existing destination, requires the destination directory to already exist, needs write permissions on both ends, and may not move across filesystems. Validate your paths first, and fall back to copy() + unlink() when a plain move isn't possible.

Practice