ZeroMQ Graceful Shutdown: Linger and Close Sockets (2026)

ZeroMQ sockets don’t actually "close" in the way you might expect; they enter a state called "lingering" where they’ll still try to send buffered messages for a specified duration.

Let’s watch a quick example. Imagine a simple publisher and subscriber. The publisher sends a few messages and then tries to shut down.

# Publisher
import zmq
import time

context = zmq.Context()
socket = context.socket(zmq.PUB)
socket.bind("tcp://*:5556")

print("Publisher sending messages...")
for i in range(5):
    message = f"Message {i}"
    socket.send_string(message)
    print(f"Sent: {message}")
    time.sleep(0.1)

print("Publisher shutting down...")
# This is where the magic (or confusion) happens
socket.close()
context.term()
print("Publisher shut down complete.")

# Subscriber
import zmq
import time

context = zmq.Context()
socket = context.socket(zmq.SUB)
socket.connect("tcp://localhost:5556")
socket.setsockopt_string(zmq.SUBSCRIBE, "") # Subscribe to everything

print("Subscriber waiting for messages...")
for _ in range(10): # Try to receive a few messages
    try:
        message = socket.recv_string(zmq.DONTWAIT)
        print(f"Received: {message}")
    except zmq.Again:
        print("No message yet...")
        time.sleep(0.2)
    except KeyboardInterrupt:
        break

print("Subscriber shutting down...")
socket.close()
context.term()
print("Subscriber shut down complete.")

If you run this, you might see the subscriber receive fewer than 5 messages, or even none, depending on timing. The publisher’s socket.close() doesn’t immediately stop it from sending. It enters a linger state.

The LINGER socket option controls how long a socket will remain active after close() is called, attempting to send any messages still in its outgoing buffer. By default, LINGER is set to 0, meaning the socket discards all unsent messages immediately upon close(). If LINGER is set to a positive value (in milliseconds), the socket will block for that duration, trying to send its buffered messages. A LINGER value of -1 means it will block indefinitely.

The problem arises when the main process exits before the linger period is over, or if the linger period is too short for the buffered messages to be sent and acknowledged. The context.term() call attempts to close all associated sockets, but if they are still lingering, their behavior can be unpredictable relative to the main thread’s termination.

To ensure graceful shutdown, you need to explicitly manage the linger period and potentially signal your application’s intent to shut down. The most common scenario is a publisher shutting down before its subscribers have acknowledged receipt of all messages.

Here’s how to manage LINGER for a more predictable shutdown:

1. Set LINGER on the sending socket: Before closing, set the LINGER option. A common value is 1000 ms (1 second) to give buffered messages a chance to go through.

   • Diagnosis: Check the current linger setting with socket.getsockopt(zmq.LINGER).
   • Fix: socket.setsockopt(zmq.LINGER, 1000)
   • Why it works: This tells the socket to wait up to 1000 milliseconds after close() is called to flush its outgoing message queue.

2. Wait for acknowledgments (if applicable): For reliable messaging patterns, your application logic might need to explicitly wait for subscribers to acknowledge receipt of critical messages before shutting down the publisher. This is more complex and often involves custom protocols.

3. Use context.term() judiciously: While context.term() cleans up, it can interrupt lingering sockets. It’s often better to explicitly close() each socket with a configured LINGER period before calling context.term().

Let’s adjust the publisher to set linger:

# Publisher with LINGER
import zmq
import time

context = zmq.Context()
socket = context.socket(zmq.PUB)
socket.bind("tcp://*:5556")

# Set linger to 1 second (1000 milliseconds)
socket.setsockopt(zmq.LINGER, 1000)

print("Publisher sending messages...")
for i in range(5):
    message = f"Message {i}"
    socket.send_string(message)
    print(f"Sent: {message}")
    time.sleep(0.1)

print("Publisher shutting down gracefully...")
# This will now block for up to 1000ms to send buffered messages
socket.close()
print("Publisher socket closed.")
context.term()
print("Publisher shut down complete.")

When you run this modified publisher with the original subscriber, you’ll notice a higher probability of the subscriber receiving all 5 messages. The socket.close() call on the publisher now initiates a 1-second grace period where it attempts to send any remaining messages in its buffer.

The most subtle point is that context.term() itself also attempts to close all sockets managed by that context. If you call socket.close() and then context.term(), the context.term() might try to close the socket again, potentially interrupting the linger period you just set. For maximum control, it’s often best to close() each socket individually with its desired LINGER setting, and then call context.term() once all sockets are explicitly closed.

The next common gotcha is how zmq.DONTWAIT on the subscriber interacts with this; if the subscriber isn’t actively recv()-ing, it won’t clear its receive queue, and even a lingering publisher might not effectively deliver messages if the subscriber isn’t ready.