File Permissions and Filesystem

Each file and directory has an owner, a group, and three permission sets: owner (u), group (g) and others (o). Each set combines read (4), write (2) and execute (1). For a directory, "execute" means "may enter and traverse", so directories need x wherever files must be reachable. PHP files never need the execute bit: the PHP interpreter reads them.

The account PHP runs as depends on the server. With Apache and mod_php (as in the official Docker image) it is the Apache user, www-data on Debian and Ubuntu, apache on Red Hat family systems. With PHP-FPM it is the user of the pool (www-data by default, but a per-site user is common and better). The Advanced Administration Handbook also describes "suexec"-style shared hosting (suPHP, mod_ruid2, mpm-itk, mod_fcgid, PHP-FPM per account) where PHP runs as the account that owns the files, and notes that this layout is more secure only for shared hosting.

The Hardening article states the principle: everything should be writable only by the owner account, except the parts of wp-content that must take user-supplied content. In practice:

When WordPress itself creates files and directories (updates, plugin installs, unzipping), it uses FS_CHMOD_FILE and FS_CHMOD_DIR. By default WP_Filesystem() derives them from the site root: fileperms( ABSPATH ) OR 0755 for directories and the mode of index.php OR 0644 for files. With a 755/644 tree that gives the 755/644 that the Hardening article promises. With a 775/664 tree it gives 775/664, which the test site confirmed.

There are two sound ways to set up ownership. Choose one per environment.

Before it installs, updates or deletes code, WordPress calls get_filesystem_method() (in wp-admin/includes/file.php). The function returns one of four transports, each a subclass of WP_Filesystem_Base:

The decision, as implemented in 7.1.3:

The function has existed since 2.5 and the filter since 2.6. The comparison uses the owner of a core file even when the context directory is wp-content/uploads, which matters to plugins (see Writing files from a plugin: the Filesystem API).

The Advanced Administration Handbook groups these under "WordPress Upgrade Constants" and asks to define as few of them as needed, and to remove one again if it did not solve the problem.

A Model B site that is updated only by its deployment pipeline sets:

Source: Advanced Administration Handbook: wp-config.php (Disable Plugin and Theme Update and Installation)

A site where PHP must update code but the files are not owned by PHP (the group-writable variant) can force the method:

Source: Advanced Administration Handbook: wp-config.php (WordPress Upgrade Constants)

With the usual umask of 022, the two mode constants keep new files at 755/644 instead of inheriting the 775/664 of a group-writable root.

For people, the Hardening article recommends SFTP whenever the host offers it: credentials and files travel encrypted. FTP sends the password in clear text, and FTPS (FTP_SSL) is a different protocol from SFTP.

For WordPress itself, the ssh2 transport needs the PECL ssh2 extension, which few hosts and none of the official WordPress images install. A key-based configuration, with the key pair readable by the PHP user and the public key installed for the deploy account on the same server, looks like this:

Source: Advanced Administration Handbook: wp-config.php (Enabling SSH Upgrade Access)

This keeps files owned by deploy, but it gives PHP a private key that can log in as the code owner. A compromised plugin can read that key, so the protection is weaker than it looks. Running WP-CLI over SSH from outside the web server (below) gives the same result without storing a key where PHP can read it.

WP-CLI loads WordPress in the shell and adds a filesystem_method filter (priority 99) that always returns direct. Whatever it writes is therefore owned by the account that runs wp, and the ownership test never applies. Three consequences, all seen on the test site:

Source: WP-CLI Commands: wp config set

Without the chmod 640 step, wp config set stops with "Could not process the 'wp-config.php' transformation. Reason: wp-config.php is not writable." WP-CLI also warns when it cannot create its cache under the user’s home directory. Set WP_CLI_CACHE_DIR or a HOME for accounts without one. WP-CLI covers the commands themselves.

The Filesystem API (added in 2.6 for updates) is the abstraction behind all of the above. A plugin that writes files should go through it, so that the write uses direct where safe and the user’s FTP/SSH credentials elsewhere. The WordPress Coding Standards (the WordPress.WP.AlternativeFunctions sniff in WPCS 3.4.1) flag direct file_put_contents() calls for the same reason.

The sequence is always the same:

request_filesystem_credentials() only works in the admin area after wp_loaded. The form reserves the field names hostname, username, password, public_key, private_key and connection_type, so a plugin form must not use them. Do not trigger the form on plugin activation; use a button the user presses, and test get_filesystem_method() first if a silent check is enough.

Tools > Site Health reports ownership problems under the "Background updates" test (since 5.2):

On a Model B site with DISALLOW_FILE_MODS this result is expected and acceptable when the deployment process keeps the site updated. The same test also lists core files that PHP cannot write, and a separate test (6.3+) checks that wp-content/upgrade-temp-backup is writable, because plugin and theme rollbacks depend on it (Updates and Auto-Updates).

Older books, WordPress All-in-One For Dummies among them, suggest 666 for files or 777 for directories whenever an upload or plugin installation fails. That makes the files writable by every account and every process on the server, and on shared hosting by every other site’s PHP code. It does not fix the actual problem, which is that PHP and the files have different owners. Even with 777 the ownership test in get_filesystem_method() still fails and the dashboard still asks for FTP credentials, as the group-writable row of the table above shows. The current guidance is 644 for files, 755 for directories, 440 or 400 for wp-config.php, and an ownership model chosen on purpose.

The official "Changing File Permissions" article itself still carries an older troubleshooting sequence that raises a directory’s mode step by step from 746 up to 767 and finally 777, and suggests 666 for .htaccess. The same article warns that 777 gives full access to any web-server process and says it should only ever be temporary. The Hardening article and the Hosting Handbook have replaced that approach: fix the owner or the PHP user, then keep 755/644.

The tables on this page were produced with the official images and the Compose file below, by changing ownership inside the web container (useradd -u 1000 -g www-data deploy, then the recipes above) and requesting the probe and dashboard URLs. Local Development Environments describes the Compose setup in general. The password comes from the environment, never from the file.

Source: Docker Hub: wordpress (official image)

The cli image is Alpine-based, where www-data is uid 82, while the Debian-based web image uses uid 33. Run WP-CLI with the web image’s numeric ids (docker compose exec -u 33:33 cli wp …, or -u 1000:33 for deploy) so that the files it writes get the intended owner.