Set Process Title

1.3.7 · active · verified Sat Mar 28

The `setproctitle` module is a C extension for Python that allows a process to change its title, which is displayed by system tools like `ps`, `top`, or `MacOS Activity Monitor`. This is particularly useful in multi-process systems (e.g., master/forked children) to identify the specific task each process is handling. The current version is 1.3.7, and it has a stable release cadence, with the last update in September 2025.

Warnings

gotcha Import and use `setproctitle` early in your program's lifetime. Code that modifies environment variables after `setproctitle` is initialized may interfere with its proper functioning.
Fix: Ensure `import setproctitle` and initial calls to `setproctitle()` or `getproctitle()` occur before any significant environment variable manipulation.
gotcha On many platforms, setting the process title may overwrite the `environ` memory area, potentially clobbering the content of `/proc/PID/environ`. While `os.environ` within Python will still work as expected, external tools reading `/proc/PID/environ` might see broken data.
Fix: To prevent `/proc/PID/environ` from being clobbered, set the `SPT_NOENV` environment variable to any non-empty value before running your Python process (e.g., `export SPT_NOENV=1`). Note that this will limit the maximum length for the process title to the length of the original command line.
gotcha The ability to change process titles is highly platform-dependent. While `setproctitle` is designed for cross-platform compatibility, its behavior and what is visible may vary significantly.
Fix: Test your application on all target operating systems and kernel versions to confirm the expected behavior of process title changes. On Windows, the module creates a Named Object, which can be read by tools like Process Explorer, as there is no direct way to change the visible process string.
deprecated Older versions of setproctitle (prior to 1.1) did not officially support Python 3.
Fix: Ensure you are using `setproctitle` version 1.1 or newer for Python 3 compatibility. The current version (1.3.7) fully supports Python 3.

Install

pip install setproctitle Install with pip

Imports

setproctitle
```
from setproctitle import setproctitle
```
While 'import setproctitle' works, directly importing 'setproctitle' (the function) is common for brevity and clarity when only this function is needed.
getproctitle
```
from setproctitle import getproctitle
```
setthreadtitle
```
from setproctitle import setthreadtitle
```
getthreadtitle
```
from setproctitle import getthreadtitle
```

Quickstart

This quickstart demonstrates how to change the current process's title using `setproctitle.setproctitle()` and retrieve it with `setproctitle.getproctitle()`. It also shows how to restore the original title.

import setproctitle
import time
import os

original_title = setproctitle.getproctitle()
print(f"Original process title: {original_title}")

new_title = f"my_worker_process_id_{os.getpid()}"
setproctitle.setproctitle(new_title)
print(f"New process title: {setproctitle.getproctitle()}")

# Simulate some work
time.sleep(5)

setproctitle.setproctitle(original_title)
print(f"Restored original process title: {setproctitle.getproctitle()}")

view raw JSON →