How to Enable Maintenance Mode in WordPress

WordPress maintenance mode is easiest to enable with WP-CLI or a .maintenance file in the correct installation directory. For a longer outage, serve a clear page with HTTP 503, protect administrator and service paths, and test caching before and after the work so a stale screen does not outlive the maintenance window.

When should you use WordPress maintenance mode?

I have seen maintenance windows go wrong for a surprisingly simple reason: nobody decided how the site would come back. WordPress maintenance mode is useful during updates, migrations, and planned changes, but the method should match the work. For a short operation, WordPress’s built-in .maintenance mechanism is usually enough. Longer work needs a clear page, an HTTP 503 Service Unavailable response, and a tested way for administrators and service integrations to reach what they need.

Before enabling anything, estimate the duration and write down the rollback command. A plugin update may finish in seconds. A database migration or theme change may take several minutes. Using the same method every time can leave visitors with a blank page or keep a stale maintenance screen active after the work is finished.

My rule: choose the smallest mechanism that fits the maintenance window, then decide how you will undo it before you start.

How do you enable WordPress maintenance mode?

The quickest method is to create a file named .maintenance in the WordPress installation directory. WordPress detects this file and displays its built-in maintenance screen. The file belongs in the WordPress root, not automatically in the document root. On VPS installations that is often /var/www/html; on some hosting accounts it is public_html.

First, verify the directory and the installation:

cd /var/www/html
wp core is-installed
pwd
hostname
ls -la wp-config.php

If wp core is-installed succeeds, WP-CLI is working in a valid WordPress directory. Seeing wp-config.php supports the check, but it is not proof by itself. The hostname line matters too. I once reached for a familiar path on a lab server before checking where I was; the red production prompt has saved me from repeating that mistake more than once.

With WP-CLI available, enable maintenance mode like this:

wp maintenance-mode activate
wp maintenance-mode status

The status output confirms the state and shows the creation time. If WP-CLI is not available, create the file directly:

cd /var/www/html
printf '<?php $upgrading = time(); ?>' > .maintenance
chmod 644 .maintenance
ls -l .maintenance

The PHP line uses the format WordPress expects for its maintenance file. Compare the ownership with the existing WordPress files. chmod 777 does not solve an ownership problem; it only grants unnecessary access.

When the work is complete, prefer WP-CLI to disable the state:

wp maintenance-mode deactivate
wp maintenance-mode status

If you used the file method:

rm -f /var/www/html/.maintenance
test ! -e /var/www/html/.maintenance && echo 'Maintenance mode is off'

Before removing anything, check pwd and hostname again. A wrong-server command is a much more expensive mistake than displaying a maintenance page.

Which WordPress maintenance mode method fits the job?

The right method depends on the change. WordPress’s own mechanism suits short core, plugin, and theme operations. A maintenance plugin helps when you need a custom message, countdown, or administrator exception. Nginx or a CDN can serve a maintenance page even when the WordPress application itself is unavailable.

Installing a maintenance plugin is not just a button click. Check the existing cache layers, security plugins, and CDN behavior first. If Cloudflare or another reverse proxy caches the old page, visitors may continue seeing it after the work is over.

A custom maintenance page should normally return 503 Service Unavailable. Returning 200 OK can make a temporary page look like permanent content to search engines. A 503 response may include a Retry-After header when the expected return time is reliable. If the duration is uncertain, leaving that header out is safer. This matches the HTTP semantics described in RFC 9110.

Administrator access needs care. A visitor without a WordPress session, a monitoring service on the same server, and a payment webhook should not automatically be subjected to the same rule.

What should you check before enabling maintenance mode?

The switch is simple. Preparation is not. Take a file and database backup before starting the update. A VPS snapshot can provide a fast rollback, but it is not a complete backup strategy. My notes in What Is a VPS Snapshot? A Guide to Point-in-Time Backups explain where snapshots fit and where they do not.

Verify that the database export completed and produced a readable file:

wp db export /var/backups/wordpress-$(date +%F-%H%M).sql
ls -lh /var/backups/wordpress-*.sql
head -n 5 /var/backups/wordpress-2026-10-04-0300.sql

The timestamp in the last command is only an example. Use the filename shown by ls. head can show that a file is not empty, but it is not a restore test. Import the backup into staging and rehearse the recovery.

Record active plugins, themes, and versions before changing anything:

wp core version
wp plugin list --status=active --format=table
wp theme list --status=active --format=table
php -v

Check PHP compatibility with the plugins and theme separately. Maintenance mode does not repair a PHP incompatibility; it only gives visitors an interim screen while you work.

If the change involves uploads or media, the same two-layer thinking from How to Increase the WordPress Upload Limit is useful. Include Nginx, PHP-FPM, and the database service in the plan, not only WordPress.

How should the maintenance page behave for visitors?

The built-in screen is plain and offers little design control. That is fine for a plugin or core update lasting a few seconds. For longer work, tell visitors what is happening, when they should try again, and where support is available if the site needs it.

WordPress creates the maintenance file temporarily during updates. Core can treat a file that remains for roughly ten minutes as an old maintenance state. That behavior is not a reliable timer for a planned outage, so remove the file explicitly when the work ends.

If the expected response is not visible, inspect browser caching, CDN caching, and the reverse proxy separately:

curl -I https://example.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/

The first command displays response headers; the second prints only the HTTP status code. A custom page should normally return 503. If it returns 200, another layer may be answering before WordPress, or the maintenance rule may be wrong.

If you change Nginx configuration, test its syntax first:

sudo nginx -t
sudo systemctl reload nginx

reload applies the configuration without immediately terminating existing workers. Still, test the rule’s scope, administrator access, and health-check endpoint. The official Nginx documentation is useful alongside How to Install and Configure Nginx on Ubuntu.

How do you preserve administrator and service access?

You may need to test the site while maintenance mode is active. The built-in .maintenance mechanism generally shows the same screen to visitors and administrators, which is one reason I prefer staging for theme and plugin development. If live-site access is necessary, consider an IP allowlist, HTTP Basic Authentication, or an application-level maintenance plugin.

IP exceptions can fail on mobile connections and office networks with changing addresses. They are not a replacement for authentication. A VPN or another authentication layer is safer than exposing an administrative path without protection.

Test these paths separately when using a custom maintenance page:

• The home page and several content URLs
• /wp-admin/ and the login screen
• REST API endpoints
• Payment, form, and webhook URLs
• The Uptime Kuma or other health-check URL

If monitoring expects only HTTP 200, it may alert during planned work. Do not simply disable monitoring; create a maintenance-window rule instead. Removing the health check can hide a genuine outage.

Test the behavior in staging before applying it to production. The gradual-release ideas in What Is a Feature Flag? A Guide to Safer Releases apply here too: test with a small group, watch the logs, and keep the rollback command ready.

What should you do if maintenance mode will not turn off?

If an update is interrupted, the .maintenance file may remain. Visitors then continue seeing a message such as “Briefly unavailable for scheduled maintenance.” Start by checking whether the file is really in the WordPress root:

cd /var/www/html
pwd
find . -maxdepth 1 -name '.maintenance' -ls
wp maintenance-mode status

If the file exists and no update is still running, remove it:

rm -f .maintenance
wp core verify-checksums

wp core verify-checksums checks for unexpected changes in WordPress core files. If it reports differences, do not overwrite the files immediately; a security tool or deliberate customization may have changed one of them.

If the file is gone but the maintenance page remains, inspect the layers in this order:

1. Check for another .maintenance file in the WordPress root.
2. Inspect PHP-FPM and Nginx logs for new errors.
3. Clear the CDN and reverse-proxy cache.
4. Check whether a maintenance plugin is still active or malfunctioning.
5. Test from another network and with another HTTP client.

Restarting PHP-FPM or the whole server without reading the logs can hide the original problem. Compare journalctl, the Nginx error log, and the WordPress debug log first. Reload only the service that actually needs it.

Can maintenance mode affect SEO and security?

Short, correctly configured maintenance should not normally create an SEO problem. Returning 503 tells crawlers that the condition is temporary. A mostly empty page returning 200 for a long time makes the content look less clearly temporary.

Do not display an administrator password, database details, server paths, or verbose errors on the maintenance page. Visible PHP errors can disclose sensitive information. Write details to logs and show visitors a short, useful message.

If you disable a security plugin during the work, check its active state as soon as the site returns. Test file permissions, ownership, cron jobs, and important form flows too. Seeing the home page load is not enough.

Use these commands for a basic post-maintenance check:

wp maintenance-mode status
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' https://example.com/
wp cron event list --due-now
wp plugin list --update=available

An item remaining in the update list is not always an error; verify the versions you intended to update. The wp cron event list --due-now output can reveal scheduled tasks that accumulated during the window.

On my Proxmox lab WordPress instance, I once checked only the public home page after a maintenance change and missed a broken login redirect. Since then, I test one authenticated path as well as the public page, then submit one harmless form if the site has forms.

That final request often tells me more than another glance at the maintenance screen.

Before You Enable WordPress Maintenance Mode

• Confirm the WordPress root directory and hostname.
• Estimate the maintenance duration and write down the rollback command.
• Export the database and verify the backup file is readable.
• Record the WordPress, plugin, theme, and PHP versions.
• Choose whether WP-CLI, .maintenance, a plugin, Nginx, or a CDN fits the job.
• Test the maintenance response, cache behavior, administrator path, and health check.
• Remove the maintenance state and verify login, forms, cron, monitoring, and the final HTTP status.

Frequently Asked Questions

Sources

• WP-CLI – maintenance-mode command — developer.wordpress.org
• WordPress Developer Reference – wp_is_maintenance_mode — developer.wordpress.org
• RFC 9110 – HTTP Semantics — rfc-editor.org
• Nginx Documentation — nginx.org