CELERY-WORKER(1)

💖 celery-worker(1) 💖

okay bestie, welcome to the celery worker manual page — yes, that's the real name, this is section 1 of the celery worker Manual, and we are gonna get you fully fluent in spinning up a worker. grab a strawberry 🍓, we're going in.

---

✨ NAME ✨

celery-worker — Start worker instance.

like. that's the whole job. start a worker. iconic honestly.

---

✨ SYNOPSIS ✨

celery worker [OPTIONS]

---

✨ DESCRIPTION ✨

Start worker instance. periodt.

🌈 Examples

the vibes, demonstrated:

$ celery --app=proj worker -l INFO
$ celery -A proj worker -l INFO -Q hipri,lopri
$ celery -A proj worker --concurrency=4
$ celery -A proj worker --concurrency=1000 -P eventlet
$ celery worker --autoscale=10,0

---

✨ OPTIONS ✨

• -n, --hostname HOSTNAME — set a custom hostname, like 'w1@%%h'. it expands: %%h (hostname), %%n (name) and %%d, (domain). no cap, your worker gets a little name tag 🎀
• -D, --detach — start the worker as a background process. it just. leaves. goes off to do its thing.
• -S, --statedb PATH — path to the state database. the extension '.db' may be appended to the filename. lowkey a small detail but we keep it.
• -l, --loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL|FATAL] — logging level. pick your volume, bestie 🔊
• -O, --optimization [default|fair] — apply an optimization profile.
• --prefetch-multiplier <prefetch multiplier> — set a custom prefetch multiplier value for this worker instance.
• --disable-prefetch — disable broker prefetching. the worker will only fetch a task when a process slot is available. ⚠️ only supported with Redis brokers.
• -c, --concurrency <concurrency> — number of child processes processing the queue. the default is the number of CPUs available on your system. she scales with your machine fr fr.
• -P, --pool [prefork|eventlet|gevent|solo|processes|threads|custom] — pool implementation. choose your fighter ✨
• -E, --task-events, --events — send task-related events that can be captured by monitors like celery events, celerymon, and others. not me sending events so the monitors stay fed 😭
• --time-limit FLOAT — enables a hard time limit (in seconds int/float) for tasks. the ULTIMATE deadline.
• --soft-time-limit FLOAT — enables a soft time limit (in seconds int/float) for tasks. gentler. still a limit though.
• --max-tasks-per-child INTEGER — maximum number of tasks a pool worker can execute before it's terminated and replaced by a new worker. out with the old 💅
• --max-memory-per-child INTEGER — maximum amount of resident memory, in KiB, that may be consumed by a child process before it will be replaced by a new one. if a single task causes a child process to exceed this limit, the task will be completed and the child process will be replaced afterwards. default: no limit. so… unlimited, if you don't say anything.
• --purge, --discard — (the page just lists the flag, no extra deets, but it's here and it counts 🫶)
• -Q, --queues COMMA SEPARATED LIST — (listed bare, no further description on the page)
• -X, --exclude-queues COMMA SEPARATED LIST — (listed bare, no further description on the page)
• -I, --include COMMA SEPARATED LIST — (listed bare, no further description on the page)
• --without-gossip — (listed bare, no further description on the page)
• --without-mingle — (listed bare, no further description on the page)
• --without-heartbeat — (listed bare, no further description on the page)
• --heartbeat-interval INTEGER — (listed bare, no further description on the page)
• --autoscale <MIN WORKERS>, <MAX WORKERS> — (listed bare, no further description on the page)
• -B, --beat — (listed bare, no further description on the page)
• -s, --schedule-filename, --schedule TEXT — (listed bare, no further description on the page)
• --scheduler TEXT — (listed bare, no further description on the page)
• -f, --logfile TEXT — log destination; defaults to stderr.
• --pidfile TEXT — PID file path; defaults to no PID file.
• --uid TEXT — drops privileges to this user ID.
• --gid TEXT — drops privileges to this group ID.
• --umask TEXT — create files and directories with this umask.
• --executable TEXT — override path to the Python executable.

---

okay that's literally everything, nothing skipped, every flag accounted for, we ate and left no crumbs 👑

heads up bestie: a bunch of these options are listed on the page with no description at all — so I'm not gonna make stuff up about what they do. flags are exact, facts are exact, that's the whole deal 💜

5.6.3 — dated 2026-05-14 — from the celery worker Manual. bye bestie, go start a worker 🦋✨