wrangler versions

The wrangler versions commands help you manage Worker Versions using Cloudflare’s Gradual Rollouts feature. Versions allow you to safely deploy changes by splitting traffic between multiple Worker versions.

Subcommands

wrangler versions view - View details of a specific version
wrangler versions list - List the 10 most recent versions
wrangler versions upload - Upload your Worker code as a new version
wrangler versions deploy - Deploy versions by splitting traffic
wrangler versions secret - Manage secrets for versioned Workers

Versions provide gradual rollout capabilities, allowing you to deploy new code incrementally and reduce risk. Changes to triggers (routes, custom domains, cron schedules) must be applied separately using wrangler triggers deploy.

view

View the details of a specific Worker Version including metadata, bindings, and configuration.

wrangler versions view <version-id> [OPTIONS]

Positional Arguments

version-id

string

required

The Worker Version ID to view (UUID format)

Options

--name

string

Name of the Worker. Can also be specified in your configuration file.

--json

boolean

default:"false"

Display output as clean JSON format instead of formatted text.

Example

# View a specific version
wrangler versions view 10000000-0000-0000-0000-000000000000

# View with JSON output
wrangler versions view 10000000-0000-0000-0000-000000000000 --json

Output

The command displays:

Version ID
Creation timestamp
Author email
Source (Wrangler, Dashboard, API, or Terraform)
Tag and message annotations (if set)
Script handlers
Compatibility date and flags
Secrets (names only, not values)
Bindings (KV, Durable Objects, R2, etc.)

list

List the 10 most recent Versions of your Worker, sorted by creation date.

wrangler versions list [OPTIONS]

Options

--name

string

Name of the Worker. Can also be specified in your configuration file.

--json

boolean

default:"false"

Display output as clean JSON format.

Example

# List recent versions
wrangler versions list

# List versions for a specific Worker
wrangler versions list --name my-worker

# Get JSON output
wrangler versions list --json

Output

For each version, displays:

Version ID
Created timestamp
Author email
Source (how the version was created)
Tag annotation
Message annotation

upload

Upload your Worker code and configuration as a new Version without deploying it to production traffic.

wrangler versions upload [SCRIPT] [OPTIONS]

Positional Arguments

script

string

The path to an entry point for your Worker. If not specified, uses the main field from your configuration file.

Options

--name

string

Name of the Worker.

--tag

string

A tag for this Worker Version (for organizational purposes).

--message

string

A descriptive message for this Worker Version.

--preview-alias

string

Name of an alias for this Worker version. Allows testing the version at a unique URL before deployment.

--compatibility-date

string

Date to use for compatibility checks. Required when uploading versions.

--compatibility-flags

string[]

Flags to use for compatibility checks. Can be specified multiple times.

--latest

boolean

default:"false"

Use the latest version of the Workers runtime.

--assets

string

Static assets directory to be served. Replaces Workers Sites.

--var

string[]

A key-value pair to be injected into the script as a variable. Format: KEY:VALUE. Can be specified multiple times.

--define

string[]

A key-value pair to be substituted in the script at build time. Format: KEY:VALUE. Can be specified multiple times.

--alias

string[]

A module pair to be substituted in the script. Format: OLD_MODULE:NEW_MODULE. Can be specified multiple times.

--jsx-factory

string

The function that is called for each JSX element.

--jsx-fragment

string

The function that is called for each JSX fragment.

--tsconfig

string

Path to a custom tsconfig.json file.

--minify

boolean

Minify the Worker script.

--upload-source-maps

boolean

Include source maps when uploading this Worker Version.

--no-bundle

boolean

default:"false"

Skip internal build steps and directly upload Worker without bundling.

--outdir

string

Output directory for the bundled Worker.

--outfile

string

Output file for the bundled Worker.

--dry-run

boolean

default:"false"

Compile the project without actually uploading the version.

Example

# Upload a new version
wrangler versions upload

# Upload with tag and message
wrangler versions upload --tag "v2.0.0" --message "Added new API endpoints"

# Upload with preview alias for testing
wrangler versions upload --preview-alias "feature-branch"

# Upload with compatibility settings
wrangler versions upload --compatibility-date "2024-01-01" --compatibility-flags "nodejs_compat"

# Dry run to validate without uploading
wrangler versions upload --dry-run

Workflow

Bundle your Worker

Wrangler bundles your Worker code using esbuild (unless --no-bundle is specified).

Upload assets

If using Workers Assets, static files are synced to Cloudflare.

Create version

The Worker code and configuration are uploaded as a new Version. The Version ID is returned.

Preview (optional)

If the version includes preview capabilities and you have a workers.dev subdomain enabled, you can access the version at a preview URL.

After uploading a version, use wrangler versions deploy to route traffic to it. Changes to triggers (routes, custom domains, cron schedules) are managed separately with wrangler triggers deploy.

deploy

Safely roll out new Versions of your Worker by splitting traffic between multiple versions.

wrangler versions deploy [VERSION-SPECS] [OPTIONS]

Positional Arguments

version-specs

string[]

Shorthand notation to deploy Worker Versions using format <version-id>@<percentage>. Multiple versions can be specified. Example: abc123@50 def456@50

Options

--name

string

Name of the Worker.

--version-id

string[]

Worker Version ID(s) to deploy. Can be specified multiple times.

--percentage

number[]

Percentage of traffic to split between Worker Versions (0-100). Must match the order of version IDs. Can be specified multiple times.

--message

string

Description of this deployment (optional).

--yes

boolean

default:"false"

Automatically accept defaults to prompts.Alias: -y

--dry-run

boolean

default:"false"

Don’t actually deploy, just validate the configuration.

Examples

# Deploy a single version to 100% of traffic
wrangler versions deploy abc12345@100

# Split traffic between two versions
wrangler versions deploy abc12345@90 def67890@10

# Use explicit flags
wrangler versions deploy --version-id abc12345 --percentage 90 --version-id def67890 --percentage 10

# Interactive mode with prompts
wrangler versions deploy

# Add a deployment message
wrangler versions deploy abc12345@100 --message "Hotfix for login bug"

# Non-interactive mode
wrangler versions deploy abc12345@100 --yes

Workflow

Review current deployment

Wrangler displays your current deployment showing which versions are receiving traffic.

Select versions

Choose which versions to deploy. You can select from:

Versions in the current deployment
The 10 most recently uploaded versions
Specific versions provided as arguments

Set traffic percentages

Specify what percentage of traffic each version should receive. Percentages must total 100%.

Add deployment message

Optionally add a message describing this deployment.

Deploy

The deployment is created and traffic is immediately routed according to the specified percentages.

Sync settings

Non-versioned settings (logpush, tail_consumers, observability) are synced if configured.

Traffic percentages must total exactly 100%. If you specify percentages that don’t sum to 100%, Wrangler will display an error and prompt you to re-enter them.

Container configuration changes (such as image, max_instances) are not gradually rolled out with versions. These changes only take effect after running wrangler deploy.

Traffic Distribution

You can specify traffic distribution in multiple ways:

Shorthand notation:

wrangler versions deploy version1@75 version2@25

Explicit flags:

wrangler versions deploy --version-id version1 --percentage 75 --version-id version2 --percentage 25

Interactive mode:
```
wrangler versions deploy
```
Wrangler will prompt you to select versions and enter percentages.

secrets

Manage secrets for versioned Workers. When you modify a secret, a new version is automatically created.

Subcommands

wrangler versions secret put <key> - Create or update a secret
wrangler versions secret delete <key> - Delete a secret
wrangler versions secret list - List secrets in deployed versions
wrangler versions secret bulk <json> - Bulk upload secrets from JSON

Secrets are version-specific. When you create or update a secret, Wrangler creates a new version based on your latest uploaded version with the updated secret binding.

See the wrangler secret documentation for detailed information on secret management. The versions secret commands work similarly but create new versions instead of directly modifying the deployed Worker.

wrangler deployments - View deployment history
wrangler rollback - Rollback to a previous version
wrangler deploy - Deploy without gradual rollouts

Configuration

Many options can be set in your wrangler.json configuration file:

wrangler.json

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-01-01",
  "compatibility_flags": ["nodejs_compat"],
  "vars": {
    "ENVIRONMENT": "production"
  },
  "observability": {
    "enabled": true,
    "head_sampling_rate": 0.01
  }
}

Best Practices

Always test with preview URLs before deploying

Use --preview-alias when uploading versions to test changes at a unique URL before routing production traffic.

Use tags and messages for tracking

Add --tag and --message to your uploads to document what changed in each version. This makes it easier to identify versions later.

Roll out gradually

Start with a small percentage of traffic (e.g., 5-10%) when deploying a new version, then increase gradually:

# Initial rollout
wrangler versions deploy new-version@10 old-version@90

# Increase if stable
wrangler versions deploy new-version@50 old-version@50

# Complete rollout
wrangler versions deploy new-version@100

Set compatibility_date in config

Always specify compatibility_date in your configuration file to ensure consistent runtime behavior across versions.

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

Subcommands

view

Positional Arguments

Options

Example

Output

list

Options

Example

Output

upload

Positional Arguments

Options

Example

Workflow

deploy

Positional Arguments

Options

Examples

Workflow

Traffic Distribution

secrets

Subcommands

Configuration

Best Practices

Build docs developers (and LLMs) love

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

​Subcommands

​view

​Positional Arguments

​Options

​Example

​Output

​list

​Options

​Example

​Output

​upload

​Positional Arguments

​Options

​Example

​Workflow

​deploy

​Positional Arguments

​Options

​Examples

​Workflow

​Traffic Distribution

​secrets

​Subcommands

​Related Commands

​Configuration

​Best Practices

Build docs developers (and LLMs) love

Subcommands

view

Positional Arguments

Options

Example

Output

list

Options

Example

Output

upload

Positional Arguments

Options

Example

Workflow

deploy

Positional Arguments

Options

Examples

Workflow

Traffic Distribution

secrets

Subcommands

Related Commands

Configuration

Best Practices