Skip to content
Pywa Cloud is not live yet - there is no running control plane or dashboard to sign up on, and the CLI package is not published. Everything on this site describes a real, working, tested system, not a roadmap - but none of it is something you can actually run against Pywa Cloud today, and commands/flags/behavior can still change before it is.

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.

  • A dependency file that declares pywa[server], pinned to a version. Any of uv.lock, pylock.toml, pyproject.toml, or requirements.txt work — 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 WhatsApp instance — found the exact same way pywa run finds one locally: a conventionally named file (main.py, app.py, wa.py, or bot.py, at the project root or under app/, bot/, wa/, or src/) with a module-level variable named wa, bot, client, app, or main.

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:

Terminal window
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-entrypoint

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:

  1. requires-python in pyproject.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.
  2. A .python-version file (the pyenv/uv convention) — used directly if supported.
  3. 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.

From your project’s directory:

Terminal window
pywa deploy

A 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:

Terminal window
pywa deploy --bot my-bot

A 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.

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.

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:

Terminal window
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-directory

The 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.

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 in dist/, say):

    .pywacloudignore
    tests/
    !dist/

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:

Terminal window
pywa cloud link <bot-id> [path]
pywa cloud unlink [path]

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:

Terminal window
export PYWA_CLOUD_TOKEN=<a deploy token>
export PYWA_CLOUD_BOT_ID=<bot-id>
pywa deploy

pywa cloud setup-ci scaffolds a ready-to-use GitHub Actions workflow around exactly this — see CI setup.