Zod 4

After a year of active development: Zod 4 is now stable! It's faster, slimmer, more tsc-efficient, and implements some long-requested features.

To simplify the migration process both for users and Zod's ecosystem of associated libraries, Zod 4 is being published alongside Zod 3 as part of the [email protected] release. To upgrade:

Then import Zod 4 from the "/v4" subpath:

Refer to the Migration guide for a complete list of breaking changes. This page covers the new features and improvements.

Zod v3.0 was released in May 2021 (!). Back then Zod had 2700 stars on GitHub and 600k weekly downloads. Today it has 37.8k stars and 31M weekly downloads (up from 23M when the beta came out 6 weeks ago!). After 24 minor versions, the Zod 3 codebase had hit a ceiling; the most commonly requested features and improvements require breaking changes.

Zod 4 fixes a number of long-standing design limitations of Zod 3 in one fell swoop, paving the way for several long-requested features and a huge leap in performance. It closes 9 of Zod's 10 most upvoted open issues. With luck, it will serve as the new foundation for many more years to come.

For a scannable breakdown of what's new, see the table of contents. Click on any item to jump to that section.

Benchmarks

You can run these benchmarks yourself in the Zod repo:

Then to run a particular benchmark:

14x faster string parsing

3x faster array parsing

6.5x faster object parsing

This runs the Moltar validation library benchmark.

Consider the following simple file:

Compiling this file with tsc --extendedDiagnostics using "zod/v3" results in >25000 type instantiations. With "zod/v4" it only results in ~175.

More importantly, Zod 4 has redesigned and simplified the generics of ZodObject and other schema classes to avoid some pernicious "instantiation explosions". For instance, chaining .extend() and .omit() repeatedly—something that previously caused compiler issues:

In Zod 3, this took 4000ms to compile; and adding additional calls to .extend() would trigger a "Possibly infinite" error. In Zod 4, this compiles in 400ms, 10x faster.

2x reduction in core bundle size

Consider the following simple script.

It's about as simple as it gets when it comes to validation. That's intentional; it's a good way to measure the core bundle size—the code that will end up in the bundle even in simple cases. We'll bundle this with rollup using both Zod 3 and Zod 4 and compare the final bundles.

The core bundle is ~57% smaller in Zod 4 (2.3x). That's good! But we can do a lot better.

Zod's method-heavy API is fundamentally difficult to tree-shake. Even our simple z.boolean() script pulls in the implementations of a bunch of methods we didn't use, like .optional(), .array(), etc. Writing slimmer implementations can only get you so far. That's where zod/v4-mini comes in.

It's a Zod variant with a functional, tree-shakable API that corresponds one-to-one with zod. Where Zod uses methods, zod/v4-mini generally uses wrapper functions:

Not all methods are gone! The parsing methods are identical in zod/v4 and zod/v4-mini.

There's also a general-purpose .check() method used to add refinements.

The following top-level refinements are available in zod/v4-mini. It should be fairly self-explanatory which methods they correspond to.

This more functional API makes it easier for bundlers to tree-shaking the APIs you don't use. While zod/v4 is still recommended for the majority of use cases, any projects with uncommonly strict bundle size constraints should consider zod/v4-mini.

6.6x reduction in core bundle size

Here's the script from above, updated to use "zod/v4-mini" instead of "zod".

When we build this with rollup, the gzipped bundle size is 1.88kb. That's an 85% (6.6x) reduction in core bundle size compared to zod@3.

Learn more on the dedicated zod/v4-mini docs page. Complete API details are mixed into existing documentation pages; code blocks contain separate tabs for "Zod" and "Zod Mini" wherever their APIs diverge.

Metadata

Zod 4 introduces a new system for adding strongly-typed metadata to your schemas. Metadata isn't stored inside the schema itself; instead it's stored in a "schema registry" that associates a schema with some typed metadata. To create a registry with z.registry():

To add schemas to your registry:

Alternatively, you can use the .register() method on a schema for convenience:

The global registry

Zod also exports a global registry z.globalRegistry that accepts some common JSON Schema-compatible metadata:

.meta()

To conveniently add a schema to z.globalRegistry, use the .meta() method.

Zod 4 introduces first-party JSON Schema conversion via z.toJSONSchema().

Any metadata in z.globalRegistry is automatically included in the JSON Schema output.

Refer to the JSON Schema docs for information on customizing the generated JSON Schema.

Recursive objects

This was an unexpected on. After years of trying to crack this problem, I finally found a way to properly infer recursive object types in Zod. To define a recursive type:

You can also represent mutually recursive types:

Unlike the Zod 3 pattern for recursive types, there's no type casting required. The resulting schemas are plain ZodObject instances and have the full set of methods available.

To validate File instances:

Internationalization

Zod 4 introduces a new locales API for globally translating error messages into different languages.

At the time of this writing only the English locale is available; There will be a call for pull request from the community shortly; this section will be updated with a list of supported languages as they become available.

The popularity of the zod-validation-error package demonstrates that there's significant demand for an official API for pretty-printing errors. If you are using that package currently, by all means continue using it.

Zod now implements a top-level z.prettifyError function for converting a ZodError to a user-friendly formatted string.

This returns the following pretty-printable multi-line string:

Currently the formatting isn't configurable; this may change in the future.

Top-level string formats

All "string formats" (email, etc.) have been promoted to top-level functions on the z module. This is both more concise and more tree-shakable. The method equivalents (z.string().email(), etc.) are still available but have been deprecated. They'll be removed in the next major version.

Custom email regex

The z.email() API now supports a custom regular expression. There is no one canonical email regex; different applications may choose to be more or less strict. For convenience Zod exports some common ones.

Zod 4 implements z.templateLiteral(). Template literal types are perhaps the biggest feature of TypeScript's type system that wasn't previously representable.

Every Zod schema type that can be stringified stores an internal regex: strings, string formats like z.email(), numbers, boolean, bigint, enums, literals, undefined/optional, null/nullable, and other template literals. The z.templateLiteral constructor concatenates these into a super-regex, so things like string formats (z.email()) are properly enforced (but custom refinements are not!).

Read the template literal docs for more info.

Number formats

New numeric "formats" have been added for representing fixed-width integer and float types. These return a ZodNumber instance with proper minimum/maximum constraints already added.

Similarly the following bigint numeric formats have also been added. These integer types exceed what can be safely represented by a number in JavaScript, so these return a ZodBigInt instance with the proper minimum/maximum constraints already added.

The existing z.coerce.boolean() API is very simple: falsy values (false, undefined, null, 0, "", NaN etc) become false, truthy values become true.

This is still a good API, and its behavior aligns with the other z.coerce APIs. But some users requested a more sophisticated "env-style" boolean coercion. To support this, Zod 4 introduces z.stringbool():

To customize the truthy and falsy values:

Refer to the z.stringbool() docs for more information.

Simplified error customization

The majority of breaking changes in Zod 4 involve the error customization APIs. They were a bit of a mess in Zod 3; Zod 4 makes things significantly more elegant, to the point where I think it's worth highlighting here.

Long story short, there is now a single, unified error parameter for customizing errors, replacing the following APIs:

Replace message with error. (The message parameter is still supported but deprecated.)

Replace invalid_type_error and required_error with error (function syntax):

Replace errorMap with error (function syntax):

Discriminated unions now support a number of schema types not previously supported, including unions, pipes, and nested objects:

Perhaps most importantly, discriminated unions now compose—you can use one discriminated union as a member of another.

Multiple values in z.literal()

The z.literal() API now optionally supports multiple values.

In Zod 3, they were stored in a ZodEffects class that wrapped the original schema. This was inconvenient, as it meant you couldn't interleave .refine() with other schema methods like .min().

In Zod 4, refinements are stored inside the schemas themselves, so the code above works as expected.

.overwrite()

The .transform() method is extremely useful, but it has one major downside: the output type is no longer introspectable at runtime. The transform function is a black box that can return anything. This means (among other things) there's no sound way to convert the schema to JSON Schema.

Zod 4 introduces a new .overwrite() method for representing transforms that don't change the inferred type. Unlike .transform(), this method returns an instance of the original class. The overwrite function is stored as a refinement, so it doesn't (and can't) modify the inferred type.

An extensible foundation: zod/v4/core

While this will not be relevant to the majority of Zod users, it's worth highlighting. The addition of zod/v4-mini necessitated the creation of a shared sub-package zod/v4/core which contains the core functionality shared between zod/v4 and zod/v4-mini.

I was resistant to this at first, but now I see it as one of Zod 4's most important features. It lets Zod level up from a simple library to a fast validation "substrate" that can be sprinkled into other libraries.

If you're building a schema library, refer to the implementations of zod/v4 and zod/v4-mini to see how to build on top of the foundation zod/v4/core provides. Don't hesitate to get in touch in GitHub discussions or via X/Bluesky for help or feedback.

I'm planning to write up a series of additional posts explaining the design process behind some major features like zod/v4-mini. I'll update this section as those get posted.

For library authors, there is now a dedicated For library authors guide that describes the best practices for building on top of Zod. It answers common questions about how to support Zod 3 & Zod 4 (including Mini) simultaneously.

Happy parsing!
— Colin McDonnell @colinhacks