WordPress Maintenance Mode: Let Only Administrators Log In

This article is a localized edition of the Japanese original. Read the Japanese original

The "maintenance" screen WordPress shows during updates blocks every request, including the login page and the admin area. Because of that, you cannot use your theme's functions.php or a plugin to "let administrators through". If you want to work while only administrators can view the site and log in, either build your own maintenance screen or put an IP address check in the .maintenance file. This article explains how the built-in mechanism works and both methods. The content was checked against the WordPress source code (wp-includes/load.php, wp-settings.php) and the official WP-CLI documentation as of November 2026.

How the built-in maintenance mode works

When updating WordPress core, plugins or themes, WordPress creates a file named .maintenance in its own directory and deletes it when the update finishes. It contains PHP with the time it was created, like this:

<?php $upgrading = 1762761600; ?>

When this file exists, WordPress behaves as follows at an early stage of loading (wp_maintenance()):

• It loads .maintenance, and if 10 minutes or more have passed since the $upgrading time, it ignores maintenance mode and serves the site normally.
• Within 10 minutes, it returns HTTP status 503 with a Retry-After: 600 header and stops.
• If wp-content/maintenance.php exists, it shows that file. Otherwise it shows WordPress's standard message.

This check happens before plugins, themes and functions.php are loaded. So excluding administrators with a "wp_maintenance filter" does not work (wp_maintenance is a function name, not a filter). There is an enable_maintenance_mode filter that can change the decision, but as the comment in WordPress says, it runs before plugins can use it and is meant for non-web runtimes. The login page (wp-login.php) is blocked in the same way, so you can't get through by logging in either.

When the site stays in “maintenance” after an update

If an update stops partway, .maintenance may be left behind. The site returns to normal 10 minutes after the time in the file, but if you want it back right away, delete .maintenance from the WordPress directory over FTP or SSH. Files starting with "." may be hidden depending on your FTP client's settings, so turn on the option to show hidden files.

After deleting it, check that the plugins or themes whose update was interrupted work correctly, and run the update again if needed.

Method 1: Show a maintenance screen to everyone except administrators (custom code)

For long work where administrators want to log in and check the site as they go, don't use the built-in .maintenance; show your own maintenance screen instead. Save the following code as wp-content/mu-plugins/simple-maintenance.php (create the mu-plugins directory if it doesn't exist). Files in mu-plugins are loaded without having to be activated.

<?php
/**
 * Plugin Name: Simple Maintenance Mode
 * Description: Shows a maintenance screen (503) to visitors who are not administrators.
 */

add_action( 'template_redirect', function () {
	// Administrators (users with the manage_options capability) see the site normally
	if ( current_user_can( 'manage_options' ) ) {
		return;
	}

	// Tell search engines this is a temporary outage and suggest when to come back (seconds)
	header( 'Retry-After: 3600' );

	wp_die(
		'<h1>Under maintenance</h1><p>We are currently performing maintenance. Please check back shortly.</p>',
		'Under maintenance',
		array( 'response' => 503 )
	);
} );

Here is how this method behaves:

• template_redirect runs just before a front-end page is displayed. It does not run on the login page (wp-login.php) or in the admin area, so administrators can log in as usual.
• Logged-in administrators see normal pages, and all other visitors see the 503 maintenance screen.
• To let Editors see the site as well, change manage_options to a capability such as edit_others_posts.
• To end maintenance, delete this file.

There are also some cautions:

• The REST API (/wp-json/) and admin-ajax.php are not blocked. This method stops only front-end pages.
• If you use a page cache plugin or a CDN, visitors may keep seeing cached pages. Clear the cache before you start and after you finish.
• Returning 503 for a long time (several days or more) can affect search results. Keep maintenance as short as possible.

How to do the same thing with a plugin is explained in "Setting up WP Maintenance Mode (LightStart)", and switching with a wp-config.php constant is explained in "How to implement maintenance mode in WordPress".

Method 2: Put an IP address check in .maintenance

For work that needs all of WordPress stopped, plugins included, such as replacing files on the server, you can create the built-in .maintenance by hand. Because .maintenance is loaded as PHP, you can change the value of $upgrading based on the IP address.

<?php
// .maintenance in the WordPress directory (for manual maintenance)
$allowed_ips = array( '203.0.113.10', '198.51.100.20' ); // IP addresses of the people doing the work
$upgrading   = in_array( $_SERVER['REMOTE_ADDR'] ?? '', $allowed_ips, true ) ? 0 : time();

• For requests from allowed IP addresses, $upgrading becomes 0 and is judged as "more than 10 minutes ago", so the site is served normally and you can log in.
• For all other requests, $upgrading is the time of the request, so the 10-minute limit never expires and the maintenance screen keeps showing.
• When the work is done, delete this file.

Cautions for this method:

• If you update WordPress or plugins from the admin area during the work, .maintenance may be overwritten and then deleted at the end of the update. If your work includes updates, check after each update that the file is still there and put it back if it isn't.
• If traffic goes through a CDN such as Cloudflare or a reverse proxy, $_SERVER['REMOTE_ADDR'] is the relay server's IP address, not the visitor's. In that setup this method can't tell visitors apart.
• If your home or office IP address changes, you lock yourself out too. In that case, delete the file over FTP or SSH.
• WP-CLI's wp maintenance-mode status reads the number in the file to decide, so it doesn't show the correct state with this code.

Change the design of the maintenance screen

You can replace the screen shown by the built-in maintenance mode by placing wp-content/maintenance.php. WordPress sends the 503 status and the Retry-After header before loading this file.

<?php
// wp-content/maintenance.php
?>
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Under maintenance</title>
</head>
<body>
<h1>Under maintenance</h1>
<p>We are currently performing maintenance. Please check back shortly.</p>
</body>
</html>

This file is loaded at a stage where almost no WordPress functions are available, so build it with HTML and CSS only. It is not used by the custom screen from Method 1.

Control maintenance mode with WP-CLI

WP-CLI has commands for the built-in maintenance mode.

# Enable (creates .maintenance)
wp maintenance-mode activate

# Show the status
wp maintenance-mode status

# Exit code 0 if active, 1 if not (for shell scripts)
wp maintenance-mode is-active

# Disable (deletes .maintenance)
wp maintenance-mode deactivate

Like an update, activate creates a .maintenance containing the time it was written. That means the site automatically returns to normal after 10 minutes. For work longer than 10 minutes, use Method 1 or Method 2.

Summary

• The built-in maintenance mode (.maintenance) blocks everything, including the login page, and is checked before plugins and functions.php. It is lifted automatically after 10 minutes.
• To let only administrators log in and work, either show a 503 screen to everyone but administrators with template_redirect (Method 1), or put an IP address check in .maintenance (Method 2).
• With either method, delete the file when you're done, clear the cache, and check the site.

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)