skip to content

In Cloudflare Workers, what is the difference between a version and a deployment, and how does wrangler deploy differ from wrangler versions upload?

level: juniorimportance: should knowfreq 45%

answer

  1. snapshot versus what serves traffic
  2. one or two versions per deployment
  3. deploy couples upload and release
  4. versions upload starts with zero traffic

basics

~20 s

A Cloudflare Workers version is an immutable snapshot of code, config and bindings; a deployment says which one or two versions serve traffic. wrangler deploy creates a version and serves it to all traffic; wrangler versions upload creates one with none.

solid answer

~40 s

A **version** captures a Worker's bundled code, static assets, bindings and compatibility settings, with an ID and optional tag and message. A **deployment** says which versions serve traffic: one at 100%, or two with percentages that total 100. `wrangler deploy` couples the steps: it uploads a new version and immediately deploys it to all traffic, and it also applies routes, custom domains and cron schedules. `wrangler versions upload` only creates the version, prints its ID and, if enabled, a Version URL; nothing changes for users until `wrangler versions deploy` includes it. Triggers are then applied separately with `wrangler triggers deploy`. A version never captures the data in KV, D1, R2 or Durable Objects.

go deeper

for a junior

Recall the two words: a version is a saved snapshot, a deployment is what serves traffic. Know that wrangler deploy does both steps at once and wrangler versions upload does only the first.

for a middle

Explain what a version captures (code, assets, bindings, compatibility settings) and what it does not (stored data). Mention that triggers need wrangler triggers deploy on the decoupled path.

for a senior

Show you know the operational edges: the first upload must be a deploy, Durable Object class changes cannot go through versions upload, and deployments status is how you confirm what is live.

for a principal

Frame the split as what lets a team put a gate between building and releasing, and say which projects are simple enough to keep the one-step wrangler deploy.

## Two separate ideas: a version and a deployment Cloudflare Workers keeps a history of every change to a Worker, and it splits that history into two kinds of record. A **version** is an immutable snapshot of the Worker at one moment. It captures the **bundled code**, the **static assets**, the **bindings** (which KV namespace, D1 database, R2 bucket or secret each `env` name points at) and the **compatibility settings** (`compatibility_date` and `compatibility_flags`). Every version gets a unique ID, records who created it, when and from where, and can carry an optional `--tag` and `--message`. A **deployment** decides which versions are serving traffic right now. A deployment references either **one version at 100%** or **two versions with a percentage split** that must total exactly 100. Each deployment is recorded too, so you can see what was live and when. One thing a version does **not** capture is the data in your storage. The rows in a D1 database, the keys in a KV namespace, the objects in an R2 bucket and the state of a Durable Object are not part of any version. A version points at those resources; it does not freeze their contents. ## wrangler deploy: the coupled path By default the two ideas move together. `wrangler deploy` bundles the project, uploads it as a **new version** and immediately creates a **deployment that sends 100% of traffic** to it, all in one step. Two other paths behave the same way by default: Workers Builds (Cloudflare's Git integration, whose deploy command defaults to `npx wrangler deploy`) and the Workers Script Upload API. `wrangler deploy` also applies the Worker's **triggers** from the Wrangler file: routes, custom domains and cron schedules. That is part of why it is the right command for a first deploy and for simple projects. ## wrangler versions upload: the decoupled path `wrangler versions upload` performs only the first half. It creates a new version and prints its **Worker Version ID**, but that version receives **no traffic**. If Version URLs are enabled for the Worker, Wrangler also prints a URL on `workers.dev` that runs just that version, so you can try it before anyone else sees it. The version goes live only when a later `wrangler versions deploy` includes it, either at 100% or as part of a split. Keeping the two steps apart is what makes gradual rollouts, manual promotion and approval gates possible. The decoupled path has a few rules worth remembering: - **Triggers are not versioned.** Changed routes, custom domains or cron schedules are not applied by `wrangler versions upload` or `wrangler versions deploy`; Wrangler tells you to run `wrangler triggers deploy` for them. - **The first upload must be a deploy.** Using `wrangler versions upload` for a Worker that does not exist yet fails; create it with `wrangler deploy` (or the create-cloudflare tool) first. - **ES modules only.** A Worker still written in the Service Worker syntax cannot be uploaded this way. - **Some changes must go through `wrangler deploy`.** A version that creates, deletes, renames or transfers a Durable Object class cannot be uploaded with `wrangler versions upload`. ## Side by side | | `wrangler deploy` | `wrangler versions upload` | |---|---|---| | Creates a version | Yes | Yes | | Traffic the new version gets | 100% at once | None until `wrangler versions deploy` | | Applies routes, domains, crons | Yes | No, use `wrangler triggers deploy` | | Works for the first upload | Yes | No | | Typical use | Simple releases, first deploy | Gradual rollouts, gated promotion | ## Seeing what is live Three read-only commands answer most questions about state: 1. `wrangler deployments status` shows the current deployment: which version or versions serve traffic, and at what percentages. 2. `wrangler deployments list` shows recent deployments, so you can see when the split changed. 3. `wrangler versions list` shows recent versions with their IDs, authors, tags and messages. The dashboard shows the same history under the Worker's **Deployments** tab. ## Why interviewers ask this The question checks that you know a Cloudflare release is not a single overwrite. Because every upload is kept as a version, you can return to an older one with `wrangler rollback`, test a version before it takes traffic, and split traffic between two versions. A candidate who says "deploy replaces the code and the old one is gone" has missed the model that makes all of that possible.

  • A team changed a route in the Wrangler file, ran wrangler versions upload and then wrangler versions deploy at 100%, but the new route never took effect. Why?
    Routes, custom domains and cron schedules are triggers, and triggers are not part of a version. `wrangler versions upload` even prints a reminder that trigger changes must be applied with `wrangler triggers deploy`. `wrangler deploy` applies them because it does everything in one step, but the decoupled path needs that extra command.
  • Can a brand-new Worker be created with wrangler versions upload?
    No. The first upload of a new Worker must use `wrangler deploy` (or the create-cloudflare tool); `wrangler versions upload` fails when the Worker does not exist yet. After that first deploy, every later release can use the upload-then-deploy path.
  • Does a version capture the data stored in the Worker's KV namespace or D1 database?
    No. A version records which resources the bindings point at, not what those resources contain. Rows, keys, objects and Durable Object state change independently, so returning to an older version does not bring back older data.

  • wrangler versions upload makes the new code live for a small share of traffic.
  • A Worker version includes the contents of its KV namespaces and D1 databases.
  • One deployment can split traffic across any number of versions.
  • wrangler versions deploy also applies changed routes and cron schedules.
  • Each wrangler deploy overwrites the old code, so there is nothing to return to.