How to Change the Thread Name in Python

March 6, 2022 Python Threading

You can set the thread name in the threading.Thread constructor or via the "name" property of the threading.Thread class.

In this tutorial you will discover how to change the name of threads in Python.

Let's get started.

Need to Change Thread Name

A thread is a thread of execution in a computer program.

Every Python program has at least one thread of execution called the main thread. Both processes and threads are created and managed by the underlying operating system.

Sometimes we may need to create additional threads in our program in order to execute code concurrently.

Python provides the ability to create and manage new threads via the threading module and the threading.Thread class.

You can learn more about Python threads in the guude:

Threading in Python: The Complete Guide

In concurrent programming, we may need to assign meaningful names to new threads.

This may be for many reasons such as:

To differentiate threads while debugging.
To differentiate threads while logging.
To execute code conditionally on the thread name.

How can we set and change thread names in Python?

How to Get the Thread Name

We can get the name of a thread via the "name" property on the threading.Thread instance.

For example:

...
# report the name of the thread
print(thread.name)

We may get a threading.Thread instance by creating a new thread ourselves.

For example:

...
# create a thread
thread = Thread()
# report the name of the thread
print(thread.name)

Or we may acquire an instance of the threading.Thread for the current thread via the current_thread() function.

For example:

...
# get the current thread instance
thread = current_thread()
# report the name of the thread
print(thread.name)

It may be helpful to get the threading.Thread instance for the current thread from within a function or code executing in a new thread so that the new thread can report properties about itself, such as its name,

Now that we know how to get a thread's name, let's look at how we might change a thread's name.

How to Change the Thread Name

The name of a thread can be set when creating a new thread.

The thread name will default to the format "Thread-%d", where "%d" is an integer for the thread number created by the process, counted from 1 sequentially up for each new thread. This means that the first new thread you might create would have the name "Thread-1".

When creating a new instance of a threading.Thread, we can specify the name of the thread via the "name" argument.

For example:

...
# create with a custom name
thread = Thread(name='MyThread')

We can also configure the thread name after the threading.Thread instance has been created via the "name" property.

For example:

...
# create a thread with default name
thread = Thread()
# set the name
thread.name = 'MyThread'

Now that we know how to change the thread name, let's look at some worked examples.

Example of Getting the Current Thread Name

We can explore how to get the name of the current thread.

First, we must acquire the threading.Thread instance for the current thread.

This can be achieved via the threading.current_thread() function.

...
# get the current thread
thread = current_thread()

Once acquired, we can report the name of the thread via the "name" attribute.

...
# report a message
print(f'Hello from thread: {thread.name}')

Tying this together, the complete example is listed below.

# SuperFastPython.com
# example of getting the current thread name
from threading import current_thread
# get the current thread
thread = current_thread()
# report a message
print(f'Hello from thread: {thread.name}')

Running the example first acquires the threading.Thread instance for the current thread and then reports the name.

In this case, we can see that the name of the current thread is "MainThread" to indicate the main thread which is the default thread created in all Python processes.

Hello from thread: MainThread

Next, let's look at how we might get the name of a new thread.

Example of Getting the Thread Name

We can explore how to get the name of a new thread.

First, we can define a function that will execute in a new thread.

We will name the function task() and it will take no arguments.

# function executed in a new thread
def task():
	# ...

Within the function, we will first get the threading.Thread instance for the thread.

...
# get the current thread
thread = current_thread()

Then we can report a message indicating the name of the new thread executing our function.

...
# report a message
print(f'Hello from a new thread: {thread.name}')

Tying this together, the complete task() function is listed below.

# function executed in a new thread
def task():
    # get the current thread
    thread = current_thread()
    # report a message
    print(f'Hello from a new thread: {thread.name}')

Next, in the main thread we can create a new threading.Thread instance and configure it to run our new task() function via the "target" attribute.

...
# create a new thread
thread = Thread(target=task)

Finally, we can call the start() method on the new thread which will begin executing the new thread, in turn calling the internal run() function and finally calling our task() function.

...
# start the new thread
thread.start()

Tying this together, the complete example of getting the thread name is listed below.

# SuperFastPython.com
# example of getting the thread name
from threading import Thread
from threading import current_thread

# function executed in a new thread
def task():
    # get the current thread
    thread = current_thread()
    # report a message
    print(f'Hello from a new thread: {thread.name}')

# create a new thread
thread = Thread(target=task)
# start the new thread
thread.start()

Running the example first creates our new thread instance then executes it.

The new thread runs our task() function first acquiring the threading.Thread instance of the new thread executing the function, then reporting its name.

In this case, we can see that the new thread used to execute our function had the default name "Thread-1" for the first new thread within the Python process.

Hello from a new thread: Thread-1

Next, let's look at how we might set a name for a new thread.

Example of Setting the Thread Name

We can explore how to set the name for a new thread.

The name for a new thread can be set via the "name" argument in the constructor to the threading.Thread class when creating a new thread.

We can update the example from the previous section with a task() function that gets the thread instance for the thread executing the function then reports the name of the thread.

First, we can set the name when constructing the new thread instance.

...
# create a new thread
thread = Thread(name='Worker', target=task)

Then the thread can be started as before by calling the start() function.

...
# start the new thread
thread.start()

Tying this together, the complete example of setting this is listed below.

# SuperFastPython.com
# example of setting the thread name
from threading import Thread
from threading import current_thread

# function executed in a new thread
def task():
    # get the current thread
    thread = current_thread()
    # report a message
    print(f'Hello from a new thread: {thread.name}')

# create a new thread
thread = Thread(name='Worker', target=task)
# start the new thread
thread.start()

Running the example creates the new threading.Thread instance configured with a custom name and or task() function as the target function.

The thread is started and the task() function acquires the thread instance and reports the name, matching the name we assigned in the constructor to the class.

Hello from a new thread: Worker

Next, let's look at how we might change the name of a thread after it has been created.

Example of Changing the Thread Name

We can explore how to change the name of a thread after it has been created.

We can update the example from the previous section and change it so that the new name of the thread is assigned after it is created instead of in the constructor.

We will use the same task() function that gets the thread instance and reports the name of the thread executing the function.

First, we can create the thread as per normal, configured to execute our custom task() function.

...
# create a new thread
thread = Thread(target=task)

Next, we can set a custom name for the thread via the "name" property.

...
# set a custom name for the new thread
thread.name = 'Worker'

Finally, we can start the new thread as before.

...
# start the new thread
thread.start()

Tying this together, the complete example of changing the thread name is listed below.

# SuperFastPython.com
# example of setting the thread name via the property
from threading import Thread
from threading import current_thread

# function executed in a new thread
def task():
    # get the current thread
    thread = current_thread()
    # report a message
    print(f'Hello from a new thread: {thread.name}')

# create a new thread
thread = Thread(target=task)
# set a custom name for the new thread
thread.name = 'Worker'
# start the new thread
thread.start()

Running the example creates the thread, sets a new name for the thread, then starts executing.

The new thread runs the task() function that gets the current thread instance and reports the thread name.

We can see that the name of the thread reported matches the name that we set after the thread was created.

Hello from a new thread: Worker

Next, let's look at an example of changing the thread name after the thread is already running.

Example of Changing the Thread Name While Running

We can explore how to change the name of a thread after the thread is already running.

We will update the example from the previous section that sets the name of the thread after the thread was constructed. We can then update the task() function to get the thread instance and report this name, then change the name and report the new name.

First, let's update the task() function.

# function executed in a new thread
def task():
	# ...

The task function is defined as before, first getting the threading.Thread instance and reporting the custom name.

...
# get the current thread
thread = current_thread()
# report a message
print(f'Hello from a new thread: {thread.name}')

Next, from within the task() function that will be executed by the thread, will change the name to 'BestWorker', then report this new name.

...
# change the name (while running)
thread.name = 'BestWorker'
# report a message
print(f'Hello again, this time from: {thread.name}')

Tying this together, the complete updated task() function is listed below.

# function executed in a new thread
def task():
    # get the current thread
    thread = current_thread()
    # report a message
    print(f'Hello from a new thread: {thread.name}')
    # change the name (while running)
    thread.name = 'BestWorker'
    # report a message
    print(f'Hello again, this time from: {thread.name}')

Finally, we can create the new thread, set a custom name and start it as we did previously.

...
# create a new thread
thread = Thread(target=task)
# set a custom name for the new thread
thread.name = 'Worker'
# start the new thread
thread.start()

Tying this together, the complete example of changing the thread name while the thread is running is listed below.

# SuperFastPython.com
# example of setting the thread name via the property
from threading import Thread
from threading import current_thread

# function executed in a new thread
def task():
    # get the current thread
    thread = current_thread()
    # report a message
    print(f'Hello from a new thread: {thread.name}')
    # change the name (while running)
    thread.name = 'BestWorker'
    # report a message
    print(f'Hello again, this time from: {thread.name}')

# create a new thread
thread = Thread(target=task)
# set a custom name for the new thread
thread.name = 'Worker'
# start the new thread
thread.start()

Running the example first creates a new thread, configures it with a custom name then starts executing our custom task() function.

The task() function first acquires the threading.Thread instance of the thread that is executing itself and reports the thread name. This matches the name assigned after the threading.Thread instance was created.

Next, the task() function changes the name of the thread, while it is running, and reports the new name. This matches the changed name.

This example shows that we can dynamically change the name of a thread while it is running, from within code that the thread is executing.

Hello from a new thread: Worker
Hello again, this time from: BestWorker

Takeaways

You now know how to change the name of threads in Python.

If you enjoyed this tutorial, you will love my book: Python Threading Jump-Start. It covers everything you need to master the topic with hands-on examples and clear explanations.