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 ​

npm install zx     # add -g to install globally

npx zx script.js         # run script without installing the zx package
npx [email protected] 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.

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 [email protected]: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

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.