Skip to main content

wp maintenance-mode activate

Overview

Put WordPress into maintenance mode immediately, showing a "Briefly unavailable for scheduled maintenance" page to all visitors. Run this before performing updates, database migrations, or any operation that could cause a broken state.

What It Does​

wp maintenance-mode activate creates a .maintenance file in the WordPress root with a $upgrading timestamp. WordPress reads this file on every request and redirects non-admin visitors to the maintenance screen.

Syntax​

wp maintenance-mode activate

Output:

Enabling Maintenance mode...
Success: Activated Maintenance mode.

Basic Usage​

wp maintenance-mode activate

Real-World Scenarios​

Scenario 1: Safe plugin update workflow​

#!/bin/bash
# safe-update.sh

echo "Activating maintenance mode..."
wp maintenance-mode activate

echo "Updating plugins..."
wp plugin update --all

echo "Flushing cache..."
wp cache flush

echo "Deactivating maintenance mode..."
wp maintenance-mode deactivate

echo "Done — site is live."

Scenario 2: Database migration with downtime window​

wp maintenance-mode activate

wp db export pre-migration-backup.sql
wp db import new-production.sql
wp search-replace 'https://staging.example.com' 'https://example.com' --skip-columns=guid
wp cache flush
wp rewrite flush

wp maintenance-mode deactivate

Scenario 3: Security incident response​

# Immediately lock the site after detecting a compromise
wp maintenance-mode activate

# Investigate and remediate...
wp core verify-checksums
wp core download --force
wp plugin verify-checksums --all

# Re-open after confirming clean
wp maintenance-mode deactivate

Scenario 4: Multi-site — activate on all subsites​

for url in $(wp site list --field=url); do
  wp maintenance-mode activate --url="$url"
  echo "Maintenance activated: $url"
done

Best Practices​

  1. Always activate before database imports — an in-progress import can serve broken pages to visitors.
  2. Combine with backup — create a database backup before the maintenance window.
  3. Deactivate immediately when done — the .maintenance file has a 10-minute auto-expiry in WordPress, but a stale file can cause issues.
  4. Test the maintenance page by opening the site in a browser (logged-out) after activation.

Troubleshooting​

ProblemCauseFix
Site still accessible after activationAdmin cookie bypasses maintenanceTest in incognito/logged-out browser
.maintenance file already existsPrevious session left itRun wp maintenance-mode deactivate to clean up
Error: Permission deniedFile system permissions issueCheck WordPress root directory write permissions

Quick Reference​

wp maintenance-mode activate           # Enable
wp maintenance-mode status             # Check state
wp maintenance-mode deactivate         # Disable

Next Steps​