Installation

Prerequisites

Before installing the Workers SDK, ensure your system meets these requirements:

Node.js

Required: Node.js 20.0.0 or higherCheck your version: node --version

Package Manager

npm, pnpm, or yarnRecommended: pnpm for faster installs

Operating System Support

Wrangler is supported on:

macOS: 13.5 or later
Windows: Windows 11
Linux: Distributions with glibc 2.35 or later

This follows the workerd OS support policy.

Installation Methods

There are several ways to install and use the Workers SDK depending on your workflow.

Method 1: Create a New Project (Recommended)

The fastest way to get started is using Create Cloudflare (C3), which scaffolds a complete project:

Run the create command

npm create cloudflare@latest

pnpm create cloudflare@latest

yarn create cloudflare@latest

This installs the latest version of create-cloudflare and runs the interactive setup wizard.

Follow the prompts

C3 will guide you through:

Project name and directory
Template selection (Hello World, frameworks, etc.)
TypeScript or JavaScript
Git initialization
Deployment option

Start developing

cd your-project-name
npm run dev

C3 automatically installs Wrangler and all necessary dependencies for your chosen template.

Method 2: Install Wrangler Globally

Install Wrangler globally to use it across multiple projects:

npm install -g wrangler

pnpm add -g wrangler

yarn global add wrangler

Verify the installation:

wrangler --version
# wrangler 4.69.0

Global installations may conflict with project-specific versions. Consider using npx or project-local installations for better version control.

Method 3: Install as Project Dependency

Add Wrangler to an existing project:

Install Wrangler

npm install wrangler --save-dev

pnpm add -D wrangler

yarn add -D wrangler

Add scripts to package.json

package.json

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "tail": "wrangler tail"
  },
  "devDependencies": {
    "wrangler": "^4.69.0"
  }
}

Run with npm scripts

npm run dev

Method 4: Use npx (No Installation)

Run Wrangler commands without installing:

npx wrangler@latest dev
npx wrangler@latest deploy

npx downloads and runs the latest version each time. This ensures you always have the newest version but may be slower.

Installing Additional Packages

Depending on your use case, you may want to install additional Workers SDK packages:

Miniflare (Local Development Runtime)

Miniflare is included with Wrangler but can be used standalone:

npm install miniflare --save-dev

pnpm add -D miniflare

yarn add -D miniflare

Current version: 4.20260305.0

Using Miniflare Programmatically

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  script: `export default {
    async fetch(request, env, ctx) {
      return new Response("Hello Miniflare!");
    }
  }`,
});

const response = await mf.dispatchFetch("http://localhost:8787/");
console.log(await response.text());

Workers Types (TypeScript Support)

Add TypeScript definitions for the Workers runtime:

npm install @cloudflare/workers-types --save-dev

pnpm add -D @cloudflare/workers-types

yarn add -D @cloudflare/workers-types

Then configure tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "lib": ["ES2022"],
    "types": ["@cloudflare/workers-types"]
  }
}

Vitest Pool Workers (Testing)

For testing Workers with Vitest in the actual runtime:

npm install @cloudflare/vitest-pool-workers --save-dev

pnpm add -D @cloudflare/vitest-pool-workers

yarn add -D @cloudflare/vitest-pool-workers

Configure vitest.config.js:

vitest.config.js

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

Configuration

After installation, configure your Worker with a wrangler.jsonc, wrangler.json, or wrangler.toml file:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "./src/index.ts",
  "compatibility_date": "2026-03-03",
  // Add your bindings here
  "vars": {
    "ENVIRONMENT": "production"
  }
}

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "./src/index.ts",
  "compatibility_date": "2026-03-03"
}

name = "my-worker"
main = "./src/index.ts"
compatibility_date = "2026-03-03"

[vars]
ENVIRONMENT = "production"

Use wrangler.jsonc for better editor support with comments and the $schema field for autocomplete.

Authentication

Before deploying Workers, authenticate with Cloudflare:

wrangler login

This opens a browser window to authorize Wrangler.

Verify authentication

wrangler whoami

You should see your account email and account ID.

Using API Tokens

For CI/CD environments, use API tokens instead:

Create an API token at dash.cloudflare.com/profile/api-tokens
Use the “Edit Cloudflare Workers” template
Set the CLOUDFLARE_API_TOKEN environment variable:

export CLOUDFLARE_API_TOKEN=your-api-token

Using Account ID and API Key

Legacy authentication (not recommended):

export CLOUDFLARE_ACCOUNT_ID=your-account-id
export CLOUDFLARE_API_KEY=your-api-key
export CLOUDFLARE_EMAIL=your-email

Version Management

Checking Versions

Check installed package versions:

# Wrangler version
wrangler --version

# All package versions in your project
npm list wrangler miniflare @cloudflare/workers-types

Updating Packages

Keep your Workers SDK packages up to date:

npm update wrangler

pnpm update wrangler

yarn upgrade wrangler

To upgrade to the latest version:

npm install wrangler@latest

pnpm add -D wrangler@latest

yarn add -D wrangler@latest

Beta Releases

Beta releases are updated frequently and not suitable for production. Use only for testing unreleased features.

Install beta releases from the main branch:

npm install https://pkg.pr.new/wrangler@main

Available beta packages:

wrangler@main
create-cloudflare@main
miniflare@main
@cloudflare/vitest-pool-workers@main

Workspace Setup (Monorepo)

For monorepo setups using pnpm workspaces:

pnpm-workspace.yaml

packages:
  - 'packages/*'
  - 'apps/*'

Install Wrangler at the workspace root:

pnpm add -Dw wrangler

Each package can have its own wrangler.jsonc configuration.

Troubleshooting

Node.js version too old

Error: This version of Wrangler requires at least Node.js v20.0.0Solution: Update Node.js using nvm or download from nodejs.org

nvm install 20
nvm use 20

EACCES permission errors

Permission errors when installing globally:Solution: Use a Node version manager (nvm) or install in a project directory instead of globally.

Module resolution errors

Cannot find module wrangler:Solution: Ensure you’re in the correct directory and dependencies are installed:

npm install

Platform-specific issues

Windows: Make sure you’re using Windows 11. Windows 10 is not supported.Linux: Verify glibc version:

ldd --version

You need glibc 2.35 or higher.

Next Steps

Now that you have the Workers SDK installed:

Create Your First Worker

Follow the quickstart guide to build and deploy

Configure Your Worker

Learn about configuration options

Set Up Testing

Configure Vitest for Workers testing

For detailed documentation on all configuration options, see the official Wrangler documentation.

Get Started

Core Tools

Development

Deployment

Platform Features

Advanced

Prerequisites

Node.js

Package Manager

Operating System Support

Installation Methods

Method 1: Create a New Project (Recommended)

Method 2: Install Wrangler Globally

Method 3: Install as Project Dependency

Method 4: Use npx (No Installation)

Installing Additional Packages

Miniflare (Local Development Runtime)

Workers Types (TypeScript Support)

Vitest Pool Workers (Testing)

Configuration

Authentication

Version Management

Checking Versions

Updating Packages

Beta Releases

Workspace Setup (Monorepo)

Troubleshooting

Next Steps

Create Your First Worker

Configure Your Worker

Set Up Testing

​Prerequisites

Node.js

Package Manager

​Operating System Support

​Installation Methods

​Method 1: Create a New Project (Recommended)

​Method 2: Install Wrangler Globally

​Method 3: Install as Project Dependency

​Method 4: Use npx (No Installation)

​Installing Additional Packages

​Miniflare (Local Development Runtime)

​Workers Types (TypeScript Support)

​Vitest Pool Workers (Testing)

​Configuration

​Authentication

​Version Management

​Checking Versions

​Updating Packages

​Beta Releases

​Workspace Setup (Monorepo)

​Troubleshooting

​Next Steps

Create Your First Worker

Configure Your Worker

Set Up Testing

Prerequisites

Operating System Support

Installation Methods

Method 1: Create a New Project (Recommended)

Method 2: Install Wrangler Globally

Method 3: Install as Project Dependency

Method 4: Use npx (No Installation)

Installing Additional Packages

Miniflare (Local Development Runtime)

Workers Types (TypeScript Support)

Vitest Pool Workers (Testing)

Configuration

Authentication

Version Management

Checking Versions

Updating Packages

Beta Releases

Workspace Setup (Monorepo)

Troubleshooting

Next Steps