Setup

Requirements

• Linux, macOS, or Windows
• JavaScript Runtime:
  • Node.js >= 12.17.0
  • Bun >= 1.0.0
  • Deno 1.x, 2.x
  • GraalVM Node.js
• 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 [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

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.