Setup

Requirements

• Linux, macOS, or Windows
• JavaScript Runtime:
  • Node.js >= 12.20.0
  • Bun >= 1.0.0
  • Deno 1.x, 2.x
  • GraalVM Node.js
  • Electron >= 11
  • WebContainers
• Some kind of bash or PowerShell

Install

::: code-group

npm install zx     # add -g to install globally

npx zx script.js         # run script without installing the zx package
npx zx@8.6.0 script.js   # pin to a specific zx version

yarn add zx

pnpm add zx

bun install zx

deno install -A npm:zx

# zx requires additional permissions: --allow-read --allow-sys --allow-env --allow-run

npx jsr add @webpod/zx
deno add jsr:@webpod/zx

# https://jsr.io/docs/using-packages

docker pull ghcr.io/google/zx:8.5.0
docker run -t ghcr.io/google/zx:8.5.0 -e="await \$({verbose: true})\`echo foo\`"
docker run -t -i -v ./:/script ghcr.io/google/zx:8.5.0 script/t.js

brew install zx

:::

Channels

zx is distributed in several versions, each with its own set of features.

| Channel | Description | Install | |----------|----------------------------------------------------------------------------------------------|----------------------| | latest | Mainline releases with the latest features and improvements. | npm i zx | | lite | A minimalistic version of zx, suitable for lightweight scripts. | npm i zx@lite | | dev | Development snapshots with the latest changes, may be unstable. | npm i zx@dev | | legacy | Legacy supporting versions for compatibility with older scripts, no new features, only bugfixes | npm i zx@<version> |

Detailed comparison: versions.

Please check the download sources carefully. Official links:

• npmjs
• GH npm
• GH repo
• GH docker
• JSR
• Homebrew

Github

To fetch zx directly from the GitHub:

# Install via git
npm i google/zx
npm i git@github.com:google/zx.git

# Fetch from the GH pkg registry
npm i --registry=https://npm.pkg.github.com @google/zx

Docker

If you'd prefer to run scripts in a container, you can pull the zx image from the ghcr.io. node:24-alpine is used as a base.

docker pull ghcr.io/google/zx:8.5.0
docker run -t ghcr.io/google/zx:8.5.0 -e="await \$({verbose: true})\`echo foo\`"
docker run -t -i -v ./:/script ghcr.io/google/zx:8.5.0 script/t.js

Bash

zx mostly relies on bash, so make sure it's available in your environment. If you're on Windows, consider using Windows Subsystem for Linux or Git Bash. By default, zx looks for bash binary, but you can switch to PowerShell by invoking usePowerShell() or usePwsh().

import { useBash, usePowerShell, usePwsh } from 'zx'

usePowerShell() // Use PowerShell.exe
usePwsh()       // Rely on pwsh binary (PowerShell v7+)
useBash()       // Switch back to bash

Electron

zx works both as a script runtime and as an app dependency.

ELECTRON_RUN_AS_NODE=1 electron script.mjs

| Context | Electron | |-----------------------------|----------| | CJS | >= 11 | | ESM, ELECTRON_RUN_AS_NODE | >= 12 | | Utility process | >= 22 | | ESM, main process | >= 28 |

app.asar is a single file for the OS, so cwd, scripts and paths passed to commands cannot point inside it. Unpack such files and use app.asar.unpacked paths instead.

WebContainers

WebContainers ship jsh instead of bash, so adjust zx at the top of your script:

$.prefix = ''
$.postfix = ' '
$.quote = (s) => `'${s.replace(/\\/g, '\\\\').replace(/'/g, `'\\''`)}'`

jsh has no set -e or pipefail, control flow, heredocs, $(...) and many coreutils like grep or sed, so use JS for these.

AsyncLocalStorage loses its context after await there, so within() isolates only its synchronous part, and later changes of $ or cd() leak out. Prefer $({ cwd }).

Package

Hybrid

zx is distributed as a hybrid package: it provides both CJS and ESM entry points.

import { $ } from 'zx'

const { $ } = require('zx')

It also contains built-in TypeScript libdefs. But @types/fs-extra and @types/node are required to be installed on user's side.

npm i -D @types/fs-extra @types/node

import { type Options } from 'zx'

const opts: Options = {
  quiet: true,
  timeout: '5s'
}

Bundled

We use esbuild to produce a static build that allows us to solve several issues at once:

• Reduce the pkg size and install time.
• Make npx (yarn dlx / bunx) invocations reproducible.
• Provide support for a wide range of Node.js versions: from 12 to 25.
• Make auditing easier: complete code is in one place.

Composite

zx exports several entry points adapted for different use cases:

• zx – the main entry point, provides all the features.
• zx/global – to populate the global scope with zx functions.
• zx/cli – to run zx scripts from the command line.
• zx/core – to use zx template spawner as part of 3rd party libraries with alternating set of utilities.

Typed

The library is written in TypeScript 5 and provides comprehensive type definitions for TS users.

• Libdefs are bundled via dts-bundle-generator.
• Compatible with TS 4.0 and later.
• Requires @types/node and @types/fs-extra to be installed.