# Minimum Node.js and pnpm Versions Required for Deploying OpenMAIC

> Deploy OpenMAIC successfully by ensuring you have the minimum Node.js and pnpm versions. Discover the required Node.js ≥22.19.0 and pnpm ≥10 for seamless deployment.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: getting-started
- Published: 2026-09-12

---

**OpenMAIC requires Node.js ≥22.19.0 and pnpm ≥10 to ensure compatibility with modern ES modules, top-level await, and workspace features used throughout the codebase.**

Deploying the THU-MAIC/OpenMAIC repository demands specific runtime prerequisites to guarantee stable operation. Understanding the minimum Node.js and pnpm versions required for deploying OpenMAIC prevents installation failures and runtime errors when setting up this modern application stack. The constraints are explicitly defined in the project's [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) and documented in the README prerequisites section.

## Node.js Version Requirements

### Minimum Version Specification

In the root [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) at lines 7-8, the `engines` field explicitly declares:

```json
"engines": {
  "node": ">=22.19.0"
}

```

This requirement is reiterated in the **Prerequisites** section of [`README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md) (lines 108-110). Node.js 22.19.0 or newer is mandatory because the codebase relies on features introduced in the Node.js 22.x series, including **top-level `await`** and **enhanced ES module support**.

## pnpm Version Requirements

### Minimum Version Specification

The project requires **pnpm version 10 or higher**. This constraint appears in the [`README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md) prerequisites and is enforced through the `packageManager` field in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) (lines 209-210), which currently specifies:

```json
"packageManager": "pnpm@10.28.0"

```

While the lockfile pins 10.28.0, any stable 10.x release satisfies the minimum requirement. The pnpm 10.x line introduced critical workspace handling improvements that OpenMAIC's monorepo structure depends on.

## Verifying Your Environment

Before running installation commands, verify your tooling matches these minimums:

```bash

# Check Node.js version (must be ≥22.19.0)

node -v

# Expected: v22.19.0 or higher

# Check pnpm version (must be ≥10)

pnpm -v

# Expected: 10.28.0 or higher

# Install dependencies only after confirming versions

pnpm install

```

If either check returns an older version, upgrade Node.js using `nvm` or your system package manager, and update pnpm via `npm i -g pnpm@latest`.

## Why These Minimums Exist

Using older versions triggers explicit failures during installation or runtime. The enforcement occurs because:

- **Node.js 22 features**: The application code utilizes syntax and APIs unavailable in Node.js 20 or earlier
- **pnpm workspace compatibility**: The repository relies on pnpm 10's enhanced workspace protocol handling for internal package linking

## Summary

- **Node.js**: Version 22.19.0 or newer, specified in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) under the `engines` field (lines 7-8)
- **pnpm**: Version 10.x or newer, declared via `packageManager` in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) (lines 209-210) and documented in [`README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md) (lines 108-110)
- **Verification**: Use `node -v` and `pnpm -v` before running `pnpm install`
- **Upgrade path**: Use `nvm` for Node.js and `npm i -g pnpm@latest` for pnpm if versions are insufficient

## Frequently Asked Questions

### What happens if I use Node.js 20 instead of 22.19.0?

The installation scripts and runtime checks will fail. OpenMAIC relies on Node.js 22-specific features such as top-level `await` and enhanced ES module resolution that are not available in version 20. You must upgrade to Node.js 22.19.0 or later to deploy successfully.

### Can I use pnpm 9.x with OpenMAIC?

No. While pnpm 9.x might install dependencies, the project explicitly requires pnpm ≥10 as documented in the [`README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md) prerequisites and enforced through the `packageManager` field in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json). Version 10 introduced workspace handling changes that the monorepo structure depends on.

### Where are the version requirements documented in the source code?

The Node.js requirement appears in the root [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) under the `engines` field (lines 7-8) and in [`README.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/README.md) (lines 108-110). The pnpm requirement is listed in the same README section and enforced via the `packageManager` entry in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) (lines 209-210).

### Is there a maximum version limit for Node.js or pnpm?

No maximum version is specified. Any stable release newer than the minimums—such as Node.js 22.x or 23.x, and pnpm 10.x or 11.x—should work correctly. The constraints define minimum floors, not ceilings.