11---
22id : run-worker-process
3- title : Worker processes - Python SDK
4- description : Shows how to run Worker processes with the Python SDK
5- sidebar_label : Worker processes
3+ title : Run a Worker - Python SDK
4+ description : Create and run a Temporal Worker using the Python SDK.
5+ sidebar_label : Run a Worker
66slug : /develop/python/workers/run-worker-process
77toc_max_heading_level : 3
88tags :
@@ -11,81 +11,110 @@ tags:
1111 - Worker
1212---
1313
14- import { ViewSourceCodeNotice } from ' @site/src/components'
14+ This page covers long-lived Workers that you host and run as persistent processes.
15+ For Workers that run on serverless compute like AWS Lambda, see [ Serverless Workers] ( /develop/python/workers/serverless-workers ) .
1516
16- ## Run a Worker Process { /* #run-a-dev-worker */ }
17+ ## Create and run a Worker { /* #run-a-dev-worker */ }
1718
18- ** How to run a Worker Process using the Temporal Python SDK.**
19+ Create a ` Worker ` with a Temporal Client, the Task Queue to poll, and the Workflows and Activities it can execute.
20+ Call ` run() ` to start polling. The Worker runs until the process is interrupted.
1921
20- The [ Worker Process] ( /workers#worker-process ) is where Workflow Functions and Activity Functions are executed.
22+ <!--SNIPSTART python-create-worker-- >
23+ [ features/snippets/worker/worker.py] ( https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.py )
24+ ``` py
25+ client = await Client.connect(" localhost:7233"
2126
22- - Each [ Worker Entity] ( /workers#worker-entity ) in the Worker Process must register the exact Workflow Types and Activity
23- Types it may execute.
24- - Each Worker Entity must also associate itself with exactly one [ Task Queue] ( /task-queue ) .
25- - Each Worker Entity polling the same Task Queue must be registered with the same Workflow Types and Activity Types.
27+ worker = Worker(
28+ client,
29+ task_queue = " my-task-queue"
30+ workflows = [HelloWorkflow],
31+ activities = [some_activity],
32+ )
33+ await worker.run()
34+ ```
35+ <!--SNIPEND-->
2636
27- A [ Worker Entity ] ( /workers#worker-entity ) is the component within a Worker Process that listens to a specific Task
28- Queue .
37+ A Worker is also an async context manager, so `async with worker:` runs it for the duration of a block.
38+ See [Shut down a Worker](#shut-down-a-worker) for the pattern most Worker processes use .
2939
30- Although multiple Worker Entities can be in a single Worker Process, a single Worker Entity Worker Process may be
31- perfectly sufficient. For more information, see the [ Worker tuning guide] ( /develop/worker-performance ) .
40+ ## Register Workflows and Activities { /* #register-types */ }
3241
33- A Worker Entity contains a Workflow Worker and/or an Activity Worker, which makes progress on Workflow Executions and
34- Activity Executions, respectively .
42+ All Workers listening to the same Task Queue must be registered to handle the same Workflow Types and Activity Types.
43+ If a Worker polls a Task for a type it does not know about, the Task fails. The Workflow Execution itself does not fail .
3544
36- To develop a Worker, use the ` Worker() ` constructor and add your Client, Task Queue, Workflows, and Activities as
37- arguments. The following code example creates a Worker that polls for tasks from the Task Queue and executes the
38- Workflow. When a Worker is created, it accepts a list of Workflows in the workflows parameter, a list of Activities in
39- the activities parameter, or both.
45+ Pass a list of Workflows in `workflows`, a list of Activities in `activities`, or both.
4046
41- < ViewSourceCodeNotice href = " https://github.com/temporalio/documentation/blob/main/sample-apps/python/your_app/run_worker_dacx.py " />
47+ Activities defined with `async def` run on the Worker's event loop. Activities defined with a plain `def` are synchronous and require an executor, so pass one in `activity_executor`:
4248
4349```python
44- from temporalio.client import Client
45- from temporalio.worker import Worker
46- # ...
47- # ...
48- async def main ():
49- client = await Client.connect(" localhost:7233"
50- worker = Worker(
51- client,
52- task_queue = " your-task-queue"
53- workflows = [YourWorkflow],
54- activities = [your_activity],
55- )
56- await worker.run()
57-
58- if __name__ == " __main__"
59- asyncio.run(main())
50+ worker = Worker(
51+ client,
52+ task_queue = " my-task-queue" ,
53+ workflows =[MyWorkflow],
54+ activities =[my_sync_activity],
55+ activity_executor =ThreadPoolExecutor(5),
56+ )
6057```
6158
62- ### Register types { /* #register-types */ }
59+ The same executor can be shared across multiple Workers.
6360
64- ** How to register types using the Temporal Python SDK. **
61+ ## Connect to Temporal Cloud { /* #connect-to-temporal-cloud */ }
6562
66- All Workers listening to the same Task Queue name must be registered to handle the exact same Workflows Types and
67- Activity Types .
63+ To run a Worker against Temporal Cloud, configure the Client connection with your Namespace address and authentication credentials.
64+ See [Connect to Temporal Cloud](/develop/python/client/temporal-client#connect-to-temporal-cloud) for setup instructions .
6865
69- If a Worker polls a Task for a Workflow Type or Activity Type it does not know about, it fails that Task. However, the
70- failure of the Task does not cause the associated Workflow Execution to fail.
66+ ## Configure Worker options { /* #worker-options */ }
7167
72- When a ` Worker ` is created, it accepts a list of Workflows in the ` workflows ` parameter, a list of Activities in the
73- ` activities ` parameter, or both .
68+ The `Worker` constructor takes keyword arguments that control concurrency limits, pollers, timeouts, and caching, including `max_concurrent_activities`, `max_concurrent_workflow_tasks`, and `max_cached_workflows`.
69+ The defaults work for most cases .
7470
75- < ViewSourceCodeNotice href = " https://github.com/temporalio/documentation/blob/main/sample-apps/python/your_app/run_worker_dacx.py " />
71+ To tune these values against real load, see [Worker performance](/develop/worker-performance) and the [Worker tuning reference](/develop/worker-tuning-reference).
7672
77- ``` python
78- # ...
79- async def main ():
80- client = await Client.connect(" localhost:7233"
81- worker = Worker(
82- client,
83- task_queue = " your-task-queue"
84- workflows = [YourWorkflow],
85- activities = [your_activity],
86- )
87- await worker.run()
88-
89- if __name__ == " __main__"
90- asyncio.run(main())
73+ ## Run a versioned Worker { /* #versioned-worker */ }
74+
75+ Set a Worker Deployment Version and enable versioning in `deployment_config`, then set a default versioning behavior for the Workflows on the Worker.
76+
77+ <!--SNIPSTART python-versioned-worker-- >
78+ [ features/snippets/worker/worker.py] ( https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.py )
79+ ``` py
80+ worker = Worker(
81+ client,
82+ task_queue = " my-task-queue"
83+ workflows = [HelloWorkflow],
84+ activities = [some_activity],
85+ deployment_config = WorkerDeploymentConfig(
86+ version = WorkerDeploymentVersion(
87+ deployment_name = " my-app"
88+ build_id = " 1.0"
89+ ),
90+ use_worker_versioning = True ,
91+ default_versioning_behavior = VersioningBehavior.PINNED ,
92+ ),
93+ )
94+ ```
95+ <!--SNIPEND-->
96+
97+ To set the behavior per Workflow instead of on the Worker, pass `versioning_behavior` to `@workflow.defn`.
98+ See [Worker Versioning](/worker-versioning) for the available versioning behaviors and how new versions roll out.
99+
100+ ## Shut down a Worker { /* #shut-down-a-worker */ }
101+
102+ Use the Worker as an async context manager and wait on an event that your signal handler sets.
103+ When the block exits, the Worker stops polling for new Tasks and waits for in-flight Tasks to finish, up to `graceful_shutdown_timeout`.
104+
105+ <!--SNIPSTART python-worker-graceful-shutdown-- >
106+ [ features/snippets/worker/worker.py] ( https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.py )
107+ ``` py
108+ worker = Worker(
109+ client,
110+ task_queue = " my-task-queue"
111+ workflows = [HelloWorkflow],
112+ activities = [some_activity],
113+ graceful_shutdown_timeout = timedelta(seconds = 30 ),
114+ )
115+ async with worker:
116+ await interrupt_event.wait()
91117```
118+ <!--SNIPEND-->
119+
120+ See [Worker shutdown](/encyclopedia/workers/worker-shutdown) for what happens to in-flight Workflow Tasks and Activities.
0 commit comments