Deploying a Pywa Bot
pywa deploy takes an ordinary pywa project and turns it into a running, always-on bot — no build
config, nothing to write beyond the pywa code you’d write anyway.
What your project needs
Section titled “What your project needs”- A dependency file that declares
pywa[server], pinned to a version. Any ofuv.lock,pylock.toml,pyproject.toml, orrequirements.txtwork — whichever your project already uses. Pywa Cloud doesn’t pin a pywa version for you; that choice stays entirely yours, like any other dependency. - A discoverable
WhatsAppinstance — found the exact same waypywa runfinds one locally: a conventionally named file (main.py,app.py,wa.py, orbot.py, at the project root or underapp/,bot/,wa/, orsrc/) with a module-level variable namedwa,bot,client,app, ormain.
That’s the whole contract — if pywa run already works on your machine, pywa deploy will work
too.
If your project doesn’t fit that convention — a different filename, a differently-named variable — point at it explicitly instead of restructuring your project:
pywa cloud bots create my-bot --entrypoint-override my_module:my_whatsapp_instance# or on an existing bot:pywa cloud bots set-entrypoint my_module:my_whatsapp_instance# back to automatic discovery:pywa cloud bots set-entrypointPython version
Section titled “Python version”Pywa Cloud currently supports 3.10 through 3.14. Which one your bot actually runs on is controlled by your project, never assumed by the platform:
requires-pythoninpyproject.toml— if your project already declares one (e.g.">=3.11", just an example, not a minimum Pywa Cloud imposes), the newest supported version satisfying it is used.- A
.python-versionfile (thepyenv/uvconvention) — used directly if supported. - Neither present → the newest version Pywa Cloud supports.
A pin that no supported version satisfies (e.g. ">=3.16", ahead of what’s supported, or "<3.10",
behind it) fails the build with a clear message listing the supported versions, rather than silently
falling back to something else.
Deploying
Section titled “Deploying”From your project’s directory:
pywa deployA directory’s first deploy asks which bot this is — pick an existing one or create a new one on
the spot — and remembers the answer, so every deploy after that is just pywa deploy again, from
anywhere in the project. To skip the prompt (useful in scripts), pass --bot directly:
pywa deploy --bot my-botA successful deploy prints something like:
📦 Packaging /path/to/my-bot...🚀 Deploying (1842 bytes)...✅ Deployed (python 3.13-slim)If something goes wrong, pywa deploy prints where it stopped and why, and exits non-zero — see
Troubleshooting for the most common failure messages and what they
mean.
Prefer a UI? The dashboard’s Deployments tab on a bot’s page does the same thing via a drag-and-drop upload, with the same deploy log and history — everything in this guide works either way, CLI or dashboard.
What actually happens
Section titled “What actually happens”Every deploy replaces the previous running version outright — it never runs the old and new
version side by side. This is deliberate, not a limitation: a pywa bot keeps some state in memory
(pending wa.listen() calls, its duplicate-webhook cache), and two copies of the same bot
processing the same WhatsApp number at once would risk a webhook handled twice, or a reply landing
on the wrong process. In practice this means a redeploy has a brief moment of real downtime — long
enough to swap the old process for the new one, not longer.
Every successful deploy is kept, so you can go back to one if a new version turns out to be broken
— see deployments rollback in the CLI reference.
Working in a monorepo
Section titled “Working in a monorepo”If your bot lives in a subdirectory alongside other things (a monorepo with several services), point the bot at that subdirectory instead of restructuring the repo:
pywa cloud bots create my-bot --bot-directory bots/backend# or on an existing bot:pywa cloud bots set-directory bots/backend# back to deploying from the project root:pywa cloud bots set-directoryThe subdirectory needs its own dependency file and its own discoverable WhatsApp instance (or
entrypoint override), exactly as if it were the whole project. Everything else you deploy alongside
it is uploaded but ignored.
What gets left out of a deploy
Section titled “What gets left out of a deploy”Two layers, so you never have to think about what “shouldn’t” be uploaded:
-
Always excluded:
.venv,.git,__pycache__,.pywacloud, and anything starting with.env. Not configurable, on purpose — nobody wants their git history or a virtualenv shipped by accident. -
.gitignore, respected by default — anything git already wouldn’t track, a deploy won’t upload either. -
.pywacloudignore— same syntax as.gitignore(one pattern per line,!to un-ignore), evaluated after.gitignore, so it can override it in either direction: exclude something git tracks but a deploy doesn’t need (tests/,docs/), or include something git ignores but a deploy does (a built frontend bundle indist/, say):.pywacloudignore tests/!dist/
Linking a directory to a bot
Section titled “Linking a directory to a bot”A directory’s first deploy writes a small .pywacloud/link.json file (git-ignored automatically)
so future deploys know which bot to target without asking. You can also set or change the link
explicitly:
pywa cloud link <bot-id> [path]pywa cloud unlink [path]Deploying from CI
Section titled “Deploying from CI”A linked directory or --bot both work fine from CI, but they still act as you — for a
credential scoped to exactly one bot and nothing else, use a
deploy token instead:
export PYWA_CLOUD_TOKEN=<a deploy token>export PYWA_CLOUD_BOT_ID=<bot-id>pywa deploypywa cloud setup-ci scaffolds a ready-to-use GitHub Actions workflow around exactly this — see
CI setup.