Zod 4.0.0 published to npm July 8th 2025
Zod version 4.0.0 was published to npm on July 8th, 2025. The package root ("zod") now exports Zod 4. All other subpaths such as "zod/v4" and "zod/v4-mini" continue to work and remain available forever.
versioning
12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Import path changes after Zod 4 npm release
After upgrading to Zod 4.0.0 on npm, imports can optionally be rewritten. Zod 4 can import from "zod" instead of "zod/v4", Zod 4 Mini can import from "zod/mini" instead of "zod/v4-mini", and Zod 3 now imports from "zod/v3" instead of "zod". All previous import paths continue to work.
Library authors peer dependency update for Zod 4
Library authors should bump their peer dependency to: "zod": "^3.25.0 || ^4.0.0". This allows libraries to support both Zod 3 and Zod 4 simultaneously. No code changes are necessary beyond the peer dependency update.
No code changes between Zod 3.25.x and 4.0.0
No code changes were made between the latest 3.25.x release and 4.0.0. The version bump was organizational to facilitate ecosystem migration, not due to implementation changes.
Zod subpath versioning strategy rationale
Zod uses subpath versioning to enable incremental ecosystem migration without a "version bump avalanche". If Zod 4.0.0 had been published immediately to npm, most libraries would have been forced to publish major version bumps to support Zod 4, creating cascading version bumps across the ecosystem. Subpath versioning allows libraries like Hono, LangChain, and React Hook Form to support both Zod 3 and Zod 4 simultaneously with a single peer dependency on "zod@^3.25.0".
Libraries supporting Zod 3 and 4 simultaneously via subpaths
Libraries can support both Zod 3 and Zod 4 simultaneously by importing from both subpaths: import * as z3 from "zod/v3" and import * as z4 from "zod/v4". They only need a single peer dependency: "zod@^3.25.0". As long as libraries import exclusively from subpaths (not the root), their implementations continue to work across the major version bump without code changes.
Why peer dependencies alone cannot support Zod 3 and 4 simultaneously
Peer dependencies cannot elegantly support two major versions of Zod simultaneously for several reasons: (1) A peer dependency spanning versions like "zod@>=3.0.0" requires painstaking manual verification of compatibility across both versions, which is impossible for Zod 3 and 4 due to fundamental class changes. (2) Optional peer dependencies lack reliable runtime detection across all platforms and bundlers, and npm v10 cannot handle the combination of peer dependencies with npm aliases needed to differentiate versions. (3) Solutions like npm aliases for dual installation result in separate package copies with no guarantee that user schemas are instances of the same ZodType class, breaking instanceof checks.
Zod 3 continues to receive updates after Zod 4 release
After Zod 4 became the default export from the package root, Zod 3 continues to be exported from the "zod/v3" subpath and remains available forever. Zod 3 continues to receive bug fixes and stability improvements.
Zod 4 breaking change: ZodType class not assignable between versions
A Zod 3 ZodType is not assignable to a Zod 4 ZodType. This fundamental incompatibility between the versions means that libraries in the ecosystem accepting user-defined Zod schemas must handle the version difference carefully, which motivated the subpath versioning strategy.
Go-inspired subpath versioning model
Zod's subpath versioning approach is analogous to how Go handles major version changes in its module system, as documented at https://go.dev/doc/modules/major-version.
Zod 4 considered stable and production-ready before npm release
Despite being exported via subpath "zod/v4" rather than from the package root initially, Zod 4 was considered stable and production-ready before the July 8th, 2025 npm release as zod@4.0.0.
Zod 3 was released May 2021 with 2700 GitHub stars
Zod v3.0 was released in May 2021 with 2700 GitHub stars and 600k weekly downloads. By Zod 4 release, it had grown to 37.8k stars and 31M weekly downloads.