pnpm Compatibility

aube is built so you can switch to it from pnpm without relearning anything. The CLI surface, the node_modules layout, and the lockfile format all mirror pnpm — but aube owns its own on-disk directories so the two tools can coexist in the same machine (and even the same project) without stepping on each other.

What's the same

• node_modules layout. aube produces the same isolated symlink layout pnpm uses with node-linker=isolated (the default): top-level entries are symlinks into node_modules/.aube/<dep_path>/node_modules/<name>. The only difference from pnpm is the directory name — .aube/ instead of .pnpm/.
• Lockfile format. aube-lock.yaml uses the same on-disk format as pnpm v9 today. The bytes round-trip; only the filename differs.
• CLI surface. Commands, flags, and exit codes mirror pnpm's. See the CLI reference.

What's different

• Aube-owned global store. aube's content-addressable store lives at ~/.aube-store/v1/files/, not ~/.pnpm-store/. Tarballs are re-downloaded on first use; subsequent installs hit the aube store. This is intentional: sharing the pnpm store means sharing its layout assumptions too, and we'd rather own our state cleanly.
• Lockfile name. aube writes aube-lock.yaml, not pnpm-lock.yaml. The pnpm file is still read automatically on first install as a migration source (alongside package-lock.json, yarn.lock, and bun.lock) and then replaced with aube-lock.yaml.
• Virtual-store directory. The per-project virtual store is node_modules/.aube/, not node_modules/.pnpm/. If a project already has a pnpm-built node_modules, aube leaves it alone and installs alongside — the two virtual stores live side by side.
• Lifecycle scripts. aube does not run lifecycle scripts from dependencies by default. Use an explicit allowlist in package.json to opt in.
• Speed. See the benchmarks.
• aube test. Equivalent to pnpm install-test: aube auto-installs before running test, so the two-step pnpm workflow becomes one command.

Migrating

Run aube install in any pnpm project. aube reads the existing pnpm-lock.yaml, writes a new aube-lock.yaml next to it, and installs into node_modules/.aube/. You can commit aube-lock.yaml and delete pnpm-lock.yaml when you're ready, or keep both around while a team transitions.