chown()

The PHP chown() Function

The chown() function changes the owner of a file or directory. On Unix-like systems, every file has an owning user and an owning group; chown() updates the user. It is mainly used by server administrators and deployment scripts that need a file to belong to a particular system account — for example, handing an uploaded file to the web-server user so it can be served or rotated.

This page covers the syntax, parameters, return value, the permissions you need for it to work, common gotchas, and runnable-style examples.

The owner is the user, not the group. To change the owning group, use chgrp(). To change read/write/execute permissions, use chmod(). These three functions are often confused.

Syntax

chown(string $filename, string|int $user): bool

• $filename — path to the file or directory whose owner you want to change.
• $user — the new owner, given either as a username string (e.g. "www-data") or as a numeric user ID (UID, e.g. 33).

It returns true on success and false on failure.

Parameters

Passing a username string requires PHP to resolve it to a UID, so the user must exist in the system's user database. Passing the UID directly skips that lookup.

Return value

chown() returns a boolean:

• true — the owner was changed successfully.
• false — the change failed (file missing, insufficient privileges, or the named user does not exist). A warning is also emitted.

Always check the return value rather than assuming success:

<?php
if (chown("example.txt", "www-data")) {
    echo "Owner changed successfully.";
} else {
    echo "Could not change owner.";
}

Who can call chown()?

This is the single most common reason chown() "doesn't work":

• On Unix, only the superuser (root) can change a file's owner. A normal, non-root process cannot give a file away to another user.
• Therefore, in a typical shared-hosting or standard PHP-FPM setup, chown() will return false unless the PHP process runs as root — which it usually should not.
• chown() is not available on Windows in the traditional sense and behaves as a no-op there.

If you only need to control access rather than ownership, prefer chmod(), which the file's owner can call without root.

Examples

Example 1: Set the owner using a username

Set the owner of example.txt to the user www-data:

<?php
$file = "example.txt";

if (chown($file, "www-data")) {
    echo "Owner of {$file} set to www-data.";
} else {
    echo "Failed to change owner of {$file}.";
}

Example 2: Set the owner using a UID

If you know the numeric user ID, pass it directly. Here 1000 is a typical UID for the first non-system user:

<?php
chown("example.txt", 1000);

Example 3: Read the owner back with fileowner()

After changing the owner, you can confirm the result. fileowner() returns the UID, and (on systems with the POSIX extension) posix_getpwuid() turns that UID into a name:

<?php
$file = "example.txt";

chown($file, "www-data");
clearstatcache(); // owner info is cached — clear it before re-reading

$uid  = fileowner($file);            // e.g. 33
$info = posix_getpwuid($uid);        // ["name" => "www-data", ...]

echo "Owner UID: {$uid}\n";
echo "Owner name: {$info['name']}\n";

clearstatcache() matters here: PHP caches file-status data, so without it you might read the old owner. See clearstatcache() for details.

Example 4: Change ownership of a directory

chown() works on directories too, but it is not recursive — it only affects the directory entry itself, not the files inside it. To change ownership of a whole tree, iterate over its contents:

<?php
$dir = "/var/www/uploads";

chown($dir, "www-data"); // the directory only

foreach (new DirectoryIterator($dir) as $item) {
    if (!$item->isDot()) {
        chown($item->getPathname(), "www-data");
    }
}

Common gotchas

• Returns false for non-root processes. This is by design — only root can reassign ownership.
• Cached owner data. Call clearstatcache() before re-reading owner info after a change.
• Symbolic links are followed. chown() changes the link's target. To change a symlink itself, use lchown().
• Not recursive. Directories require manual iteration (Example 4).
• open_basedir / disable_functions. Many hosts disable chown() for security; check php.ini if it silently fails.

Related functions

• chgrp() — change the owning group of a file.
• chmod() — change file permissions (read/write/execute).
• fileowner() — get the UID of a file's owner.
• filegroup() — get the GID of a file's group.
• lchown() — change the owner of a symbolic link itself.
• clearstatcache() — clear PHP's cached file-status data.

Conclusion

The chown() function changes the owner of a file or directory, accepting either a username string or a numeric UID and returning a boolean. The key thing to remember is that changing ownership requires superuser privileges, which is why it so often returns false in everyday web code. When you only need to control access, reach for chmod() instead; to change the group, use chgrp().

Practice