Skip to main content

​
Overview

The bench restart command restarts production services managed by Supervisor or systemd. This is used in production environments to apply changes after code updates, configuration changes, or to recover from errors.

​
Syntax

bench restart [OPTIONS]

​
Options

​
--web
boolean
default:"false"
Restart only the web workers (Gunicorn processes).
bench restart --web
​
--supervisor
boolean
default:"false"
Restart Supervisor-managed processes. This is the default if no other options are specified.
bench restart --supervisor
​
--systemd
boolean
default:"false"
Restart systemd units instead of Supervisor processes.
bench restart --systemd

​
Usage Examples

​
Default Restart (Supervisor)

Restart all Supervisor-managed processes: 
bench restart
This is equivalent to: 
bench restart --supervisor

​
Restart Web Workers Only

Restart only the Gunicorn web processes: 
bench restart --web
Useful when:
  • You’ve updated Python code
  • You’ve changed configuration files
  • Web workers are unresponsive

​
Restart systemd Services

For benches managed by systemd: 
bench restart --systemd

​
Restart Web with systemd

Restart only web services under systemd: 
bench restart --web --systemd

​
What Gets Restarted

​
Supervisor Mode (Default)

When using Supervisor, the following processes are restarted:
  • Web Workers: Gunicorn processes serving web requests
  • Background Workers:
    • frappe-bench-workers:frappe-bench-frappe-default-worker-0
    • frappe-bench-workers:frappe-bench-frappe-short-worker-0
    • frappe-bench-workers:frappe-bench-frappe-long-worker-0
  • Web Server: Node.js server
  • SocketIO: Real-time communication server
  • Scheduler: Background job scheduler

​
systemd Mode

When using systemd, these units are restarted:
  • frappe-bench-web.service - Web server
  • frappe-bench-workers.target - All worker services
  • frappe-bench-socketio.service - SocketIO server
  • frappe-bench-redis-cache.service - Redis cache (if managed by systemd)
  • frappe-bench-redis-queue.service - Redis queue (if managed by systemd)

​
Common Patterns

​
After Code Updates

Restart after pulling code changes: 
cd /home/frappe/frappe-bench
git -C apps/frappe pull
bench restart --web

​
After Configuration Changes

Restart after modifying site config: 
bench --site site1.local set-config key value
bench restart

​
Graceful Restart in Production

Minimize downtime with a rolling restart: 
# Enable maintenance mode
bench --site all set-maintenance-mode on

# Restart services
bench restart

# Disable maintenance mode
bench --site all set-maintenance-mode off

​
Restart Individual Workers

For fine-grained control, use supervisorctl directly: 
sudo supervisorctl restart frappe-bench-workers:frappe-bench-frappe-default-worker-0

​
When to Use

​
Restart Required

You must restart after:
  • Updating Python code in apps
  • Modifying hooks.py
  • Changing common_site_config.json
  • Installing/updating Python packages
  • Applying hotfixes

​
Restart NOT Required

You don’t need to restart after:
  • Changing JavaScript/CSS (just rebuild assets)
  • Modifying DocType schemas (changes are immediate)
  • Updating data in documents
  • Changing site_config.json for most settings

​
Web-Only Restart Sufficient

Restart only web workers when:
  • You’ve only changed web-facing code
  • Background workers are processing important jobs
  • You want to minimize disruption

​
Supervisor vs systemd

​
Supervisor (Traditional)

Pros:
  • Simpler configuration
  • Better log management
  • Easier to debug
  • More common in Frappe deployments
Cons:
  • Requires separate service
  • Less integration with system
Usage: 
# Check status
sudo supervisorctl status

# Restart via bench
bench restart --supervisor

# Or directly
sudo supervisorctl restart frappe-bench:*

​
systemd (Modern)

Pros:
  • Native system integration
  • Better resource management
  • Automatic restart on failure
  • Service dependencies
Cons:
  • More complex setup
  • Logs via journalctl
  • Less Frappe-specific tooling
Usage: 
# Check status
sudo systemctl status frappe-bench-web

# Restart via bench
bench restart --systemd

# Or directly
sudo systemctl restart frappe-bench-web frappe-bench-workers.target

​
Troubleshooting

​
Restart Command Hangs

If restart doesn’t complete: 
# Kill and restart manually
sudo supervisorctl stop all
sudo pkill -f gunicorn
sudo pkill -f node
sudo supervisorctl start all

​
Workers Not Responding

Force restart with supervisorctl: 
sudo supervisorctl restart frappe-bench-workers:*

​
Permission Denied

Restart commands may require sudo: 
sudo bench restart
# or
sudo -H -u frappe bash -c 'cd /home/frappe/frappe-bench && bench restart'

​
Processes Not Starting

Check logs: 
# Supervisor logs
sudo tail -f /var/log/supervisor/*.log

# systemd logs
sudo journalctl -u frappe-bench-web -f

​
Config Changes Not Applied

Force reload configuration: 
sudo supervisorctl reread
sudo supervisorctl update
bench restart

​
Zero-Downtime Restart

For mission-critical production: 
# Set up multiple web workers
# Edit config/supervisor.conf to have multiple web processes

# Reload instead of restart
sudo supervisorctl signal HUP frappe-bench-web:frappe-bench-frappe-web

​
Monitoring Restarts

​
Check Process Status

# Supervisor
sudo supervisorctl status

# systemd
sudo systemctl status frappe-bench-*

​
View Logs During Restart

# Follow supervisor logs
sudo tail -f /var/log/supervisor/*.log

# Follow systemd logs
sudo journalctl -f -u frappe-bench-web

​
Verify Restart Success

# Check if all processes are running
sudo supervisorctl status | grep -v RUNNING

# Test web interface
curl -I http://localhost

# Check bench status
bench doctor

​
Performance Impact

​
Restart Duration

Typical restart times:
  • Web workers: 5-10 seconds
  • All processes: 15-30 seconds
  • Large benches: 30-60 seconds

​
During Restart

  • Active requests may fail
  • Background jobs pause
  • WebSocket connections drop
  • Users may see connection errors

​
Minimize Impact

# Schedule during low-traffic periods
# Use maintenance mode
bench --site all set-maintenance-mode on
bench restart
bench --site all set-maintenance-mode off

# Or restart in stages
bench restart --web
sleep 5
sudo supervisorctl restart frappe-bench-workers:*

​
Automated Restart

Set up automatic restart on failure with Supervisor: 
[program:frappe-bench-web]
autorestart=true
startsecs=10
stopwaitsecs=60
For systemd, use restart policies: 
[Service]
Restart=on-failure
RestartSec=10s

Build docs developers (and LLMs) love

Get started for freeTalk to us