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:
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?
Run loops using all CPUs, download your FREE book to learn how.
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:
|
1 2 3 |
... # report the name of the thread print(thread.name) |
We may get a threading.Thread instance by creating a new thread ourselves.
For example:
|
1 2 3 4 5 |
... # 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:
|
1 2 3 4 5 |
... # 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:
|
1 2 3 |
... # 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:
|
1 2 3 4 5 |
... # 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.
Free Python Threading Course
Download your FREE threading PDF cheat sheet and get BONUS access to my free 7-day crash course on the threading API.
Discover how to use the Python threading module including how to create and start new threads and how to use a mutex locks and semaphores
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.
|
1 2 3 |
... # get the current thread thread = current_thread() |
Once acquired, we can report the name of the thread via the “name” attribute.
|
1 2 3 |
... # report a message print(f'Hello from thread: {thread.name}') |
Tying this together, the complete example is listed below.
|
1 2 3 4 5 6 7 |
# 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.
|
1 |
Hello from thread: MainThread |
Next, let’s look at how we might get the name of a new thread.
Overwhelmed by the python concurrency APIs?
Find relief, download my FREE Python Concurrency Mind Maps
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.
|
1 2 3 |
# function executed in a new thread def task(): # ... |
Within the function, we will first get the threading.Thread instance for the thread.
|
1 2 3 |
... # get the current thread thread = current_thread() |
Then we can report a message indicating the name of the new thread executing our function.
|
1 2 3 |
... # report a message print(f'Hello from a new thread: {thread.name}') |
Tying this together, the complete task() function is listed below.
|
1 2 3 4 5 6 |
# 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.
|
1 2 3 |
... # 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.
|
1 2 3 |
... # start the new thread thread.start() |
Tying this together, the complete example of getting the thread name is listed below.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# 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.
|
1 |
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.
|
1 2 3 |
... # create a new thread thread = Thread(name='Worker', target=task) |
Then the thread can be started as before by calling the start() function.
|
1 2 3 |
... # start the new thread thread.start() |
Tying this together, the complete example of setting this is listed below.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# 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.
|
1 |
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.
|
1 2 3 |
... # create a new thread thread = Thread(target=task) |
Next, we can set a custom name for the thread via the “name” property.
|
1 2 3 |
... # set a custom name for the new thread thread.name = 'Worker' |
Finally, we can start the new thread as before.
|
1 2 3 |
... # start the new thread thread.start() |
Tying this together, the complete example of changing the thread name is listed below.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# 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.
|
1 |
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.
|
1 2 3 |
# 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.
|
1 2 3 4 5 |
... # 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.
|
1 2 3 4 5 |
... # 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.
|
1 2 3 4 5 6 7 8 9 10 |
# 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.
|
1 2 3 4 5 6 7 |
... # 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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
# 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.
|
1 2 |
Hello from a new thread: Worker Hello again, this time from: BestWorker |
Further Reading
This section provides additional resources that you may find helpful.
Python Threading Books
- Python Threading Jump-Start, Jason Brownlee (my book!)
- Threading API Interview Questions
- Threading Module API Cheat Sheet
I also recommend specific chapters in the following books:
- Python Cookbook, David Beazley and Brian Jones, 2013.
- See: Chapter 12: Concurrency
- Effective Python, Brett Slatkin, 2019.
- See: Chapter 7: Concurrency and Parallelism
- Python in a Nutshell, Alex Martelli, et al., 2017.
- See: Chapter: 14: Threads and Processes
Guides
- Python Threading: The Complete Guide
- Python ThreadPoolExecutor: The Complete Guide
- Python ThreadPool: The Complete Guide
APIs
References
Takeaways
You now know how to change the name of threads in Python.
Do you have any questions?
Ask your questions in the comments below and I will do my best to answer.
Photo by Francisco Requena on Unsplash
Leave a Reply