Python Signal Handling – Graceful Shutdown with SIGINT, SIGTERM

Introduction – Why Handle Signals in Python?

Signals are a core part of Unix-based systems. They allow the OS or other processes to notify your program about events such as:

• Ctrl+C (interrupt via SIGINT)
• Termination (SIGTERM)
• Hang-up (SIGHUP)
• Child process events (SIGCHLD)

With Python’s built-in signal module, you can intercept and handle these events to:

• Shutdown cleanly
• Save state before exit
• Restart services automatically
• Handle timeouts or inter-process communication

In this guide, you’ll learn:

• What signals are and how they work in Python
• How to catch signals like SIGINT and SIGTERM
• How to safely clean up resources using signal handlers
• Best practices and limitations of signal handling

What Is a Signal?

A signal is a software interrupt sent to a process to notify it of an event (e.g., kill signal, interrupt signal).

In Python, you can register handlers that are executed when a signal is received.

Setting Up a Signal Handler

Basic Signal Handler Example

import signal
import sys

def handle_sigint(signum, frame):
    print("Caught SIGINT (Ctrl+C). Exiting gracefully...")
    sys.exit(0)

signal.signal(signal.SIGINT, handle_sigint)

while True:
    pass  # Keep running

Pressing Ctrl+C will now trigger the handler and exit cleanly.

Supported Signals (Common)

Example – Handle SIGTERM

def handle_sigterm(signum, frame):
    print("Caught SIGTERM. Cleaning up...")
    sys.exit(0)

signal.signal(signal.SIGTERM, handle_sigterm)

Useful in Docker containers, daemonized apps, or system services.

Signal Parameters

The signal handler always accepts two arguments:

def handler(signum, frame):
    print(f"Signal received: {signum}")

• signum: signal number (e.g., 2 for SIGINT)
• frame: current stack frame (useful for debugging)

Using signal.SIGALRM for Timeouts

import time

def timeout_handler(signum, frame):
    raise TimeoutError("Operation timed out!")

signal.signal(signal.SIGALRM, timeout_handler)
signal.alarm(3)  # Set a 3-second timer

try:
    time.sleep(5)  # This will be interrupted
except TimeoutError as e:
    print(e)

Raises a TimeoutError after 3 seconds.

📵 Limitations of Signal Handling in Python

Real-World Use Case – Graceful Shutdown

import time

running = True

def handle_exit(signum, frame):
    global running
    print("Shutdown signal received.")
    running = False

signal.signal(signal.SIGINT, handle_exit)
signal.signal(signal.SIGTERM, handle_exit)

print("Running... Press Ctrl+C to stop.")
while running:
    time.sleep(1)

print("Clean exit complete.")

Ideal for cleanup scripts, cron jobs, long-running services.

Best Practices

Summary – Recap & Next Steps

Python signal handling allows you to gracefully manage external interrupts and control how your application shuts down or responds to external events.

Key Takeaways:

• Use signal.signal() to register signal handlers
• Handle SIGINT, SIGTERM, and SIGHUP for clean shutdowns
• Signals only affect the main thread
• Use signal.alarm() to implement timeouts

Real-World Relevance:
Used in system daemons, CLI tools, Docker containers, and supervised services like Gunicorn, Celery, or custom schedulers.

FAQ – Python Signal Handling

Can Python catch Ctrl+C?

Yes. Use signal.SIGINT to handle keyboard interrupts.

Can I handle signals in threads?

No. Signal handlers only work in the main thread.

How do I stop a long-running loop using signals?

Set a global flag in the handler and check it inside the loop.

What signals can’t be handled?

• SIGKILL (9)
• SIGSTOP (19)

These cannot be caught or ignored.

What’s the difference between SIGINT and SIGTERM?

• SIGINT: Sent by keyboard (Ctrl+C)
• SIGTERM: Sent by system/process, often to gracefully stop a program