Environment:Promptfoo Promptfoo Node Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Runtime |
| Last Updated | 2026-02-14 08:00 GMT |
Overview
Node.js runtime environment requiring version ^20.20.0 or >=22.22.0, with ESM module support and optional Bun/Deno compatibility.
Description
Promptfoo is a Node.js CLI application distributed as an npm package. It requires specific Node.js versions because several dependencies use ES2024 features (e.g., the RegExp `/v` flag in `string-width` via `ora`) that cause cryptic syntax errors on older Node.js versions. The entrypoint performs an explicit version check before loading any modules to provide a helpful error message. Alternative JavaScript runtimes (Bun and Deno) are also supported and skip the version check since they support modern JS features natively.
The project uses ESM modules (`"type": "module"` in package.json) and exports both ESM and CommonJS builds. The `engine-strict=true` setting in `.npmrc` enforces version constraints at install time.
Usage
This environment is required for all promptfoo operations: CLI usage, library integration, server mode, and development. Every implementation in the codebase depends on this runtime environment.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, Windows | Cross-platform; WSL2 recommended on Windows |
| Runtime | Node.js ^20.20.0 or >=22.22.0 | Enforced at both install time (.npmrc) and runtime (entrypoint.ts) |
| Runtime (Alt) | Bun or Deno | Version check skipped; must support ES2024 features |
| Package Manager | npm, pnpm, or yarn | Workspaces used for src/app and site |
| Disk | ~200MB | For node_modules and build artifacts |
Dependencies
System Packages
- `node` ^20.20.0 || >=22.22.0
- `npm` (or `pnpm` / `yarn`)
- `git` (for development workflow)
Node.js Packages (Core)
- `better-sqlite3` >= 12.6.2 (native addon, requires build tools)
- `commander` >= 14.0.3 (CLI framework)
- `express` >= 5.2.1 (server)
- `drizzle-orm` >= 0.45.1 (database ORM)
- `openai` >= 6.18.0 (OpenAI provider)
- `@anthropic-ai/sdk` >= 0.74.0 (Anthropic provider)
- `zod` >= 4.3.6 (schema validation)
Credentials
No credentials are required for the base runtime environment. Provider-specific API keys are documented in Environment:Promptfoo_Promptfoo_Provider_API_Keys.
Quick Install
# Install Node.js (using nvm)
nvm install 22
nvm use 22
# Install promptfoo globally
npm install -g promptfoo
# Or install as a project dependency
npm install promptfoo
Code Evidence
Version check from `src/entrypoint.ts:17-39`:
// Use injected value at build time, fallback to 20 for development/testing
const minNodeVersion =
typeof __PROMPTFOO_MIN_NODE_VERSION__ !== 'undefined' ? __PROMPTFOO_MIN_NODE_VERSION__ : 20;
// Skip version check for alternative runtimes (Bun, Deno)
const isBun = typeof (globalThis as Record<string, unknown>).Bun !== 'undefined';
const isDeno = typeof (globalThis as Record<string, unknown>).Deno !== 'undefined';
if (!isBun && !isDeno) {
const major = parseInt(process.version.slice(1), 10);
if (Number.isNaN(major)) {
console.error(`Unexpected Node.js version format: ${process.version}.`);
process.exit(1);
}
if (major < minNodeVersion) {
console.error(`Node.js ${process.version} is not supported. Please upgrade to Node.js ${minNodeVersion} or later.`);
process.exit(1);
}
}
Engine constraint from `package.json:31-33`:
"engines": {
"node": "^20.20.0 || >=22.22.0"
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Node.js vXX.X.X is not supported. Please upgrade to Node.js 20 or later.` | Node.js version too old | Upgrade Node.js: `nvm install 22 && nvm use 22` |
| `SyntaxError: Invalid regular expression: invalid class set expression` | Node.js < 20 encountering ES2024 RegExp `/v` flag | Upgrade Node.js to ^20.20.0 or >=22.22.0 |
| `Unexpected Node.js version format` | Non-standard Node.js build with malformed version string | Use official Node.js distribution |
| `npm ERR! engine Unsupported engine` | npm strict engine checking blocked install | Upgrade Node.js or use `--ignore-engines` flag |
Compatibility Notes
- Bun: Supported as an alternative runtime. Version check is skipped. All modern JS features are available natively.
- Deno: Supported as an alternative runtime. Version check is skipped. Must support ES2024 features.
- Node.js 21: Not supported due to the `^20.20.0 || >=22.22.0` constraint (excludes 21.x).
- ESM Only: The package uses `"type": "module"`. CommonJS consumers must use the `.cjs` export.
- Native Addons: `better-sqlite3` requires C++ build tools (build-essential on Linux, Xcode CLI on macOS).