# zod > TypeScript-first schema declaration and validation library with static type inference Latest version **4.6.5** (published 2026-09-13) · MIT license · 0 weekly downloads ## Install ```sh npm install zod pnpm add zod yarn add zod bun add zod ``` ## Health **Score 80/100 (A)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo. Warnings: low downloads. ## Facts | | | |---|---| | Version | 4.6.5 | | Published | 2026-09-13 | | First published | 2020-03-07 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 0 | | Unpacked size | 5.9 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 43939 | | Author | Colin McDonnell | | Maintainers | colinhacks | | Keywords | typescript, schema, validation, type, inference | ## Links - npm: https://www.npmjs.com/package/zod - Repository: https://github.com/colinhacks/zod - Homepage: https://zod.dev - Issues: https://github.com/colinhacks/zod/issues - Funding: https://github.com/sponsors/colinhacks - npm.io page: https://npm.io/package/zod ## Alternatives - [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads - [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads - [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads - [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads - [@oridune/validator](https://npm.io/package/@oridune/validator.md) — 16 weekly downloads ## Recent versions - 4.6.5 (latest) — 2026-09-13 - 4.5.0-canary.20260828T171753 (canary) — 2026-08-28 - 4.1.13-beta.0 (beta) — 2025-10-15 - 3.25.68-alpha.11 (alpha) — 2025-06-24 - 3.25.0-beta.20250519T094321 (next) — 2025-05-19 - 4.6.4 — 2026-09-13 - 4.6.3 — 2026-09-12 - 4.6.2 — 2026-09-10 - 4.6.1 — 2026-09-09 - 4.6.0 — 2026-09-09 - 4.5.4 — 2026-08-29 - 4.5.3 — 2026-08-29 - 4.5.2 — 2026-08-29 - 4.5.0-canary.20260825T051321 — 2026-08-28 - 4.5.0-canary.20260828T163622 — 2026-08-28 - … 996 more at https://npm.io/package/zod/versions ## README

Zod

TypeScript-first schema validation with static type inference
by @colinhacks

Docs • Discord • 𝕏 • Bluesky

### [Read the docs →](https://zod.dev/api)

## What is Zod? Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result. ```ts import * as z from "zod"; const User = z.object({ name: z.string(), }); // some untrusted data... const input = { /* stuff */ }; // the parsed result is validated and type safe! const data = User.parse(input); // so you can use it with confidence :) console.log(data.name); ```
## Features - Zero external dependencies - Works in Node.js and all modern browsers - Tiny: `2kb` core bundle (gzipped) - Immutable API: methods return a new instance - Concise interface - Works with TypeScript and plain JS - Built-in JSON Schema conversion - Extensive ecosystem
## Installation ```sh npm install zod ```
## Basic usage Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema. ```ts import * as z from "zod"; const Player = z.object({ username: z.string(), xp: z.number(), }); ``` ### Parsing data Given any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input. ```ts Player.parse({ username: "billie", xp: 100 }); // => returns { username: "billie", xp: 100 } ``` **Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.parseAsync()` method instead. ```ts const schema = z.string().refine(async (val) => val.length <= 8); await schema.parseAsync("hello"); // => "hello" ``` ### AOT compilation For hot validation paths, `z.compile(schema)` returns a schema clone with an ahead-of-time compiled fast path. Valid inputs take the compiled path; invalid inputs fall back to the regular parser so error reporting stays identical. Across a 55-schema benchmark the median speedup is **2.4x**, and it scales with how much work the schema does per parse: a large array of objects is ~9x, a 20-key object ~9x, a nested object ~4.5x, while a bare `z.string()` gains nothing — compilation removes per-node dispatch and allocation, and a single `typeof` has none to remove. ```ts const CompiledPlayer = z.compile(Player); CompiledPlayer.parse({ username: "billie", xp: 100 }); ``` To enable compilation globally for schemas constructed after import: ```ts import "zod/compile"; // place before modules that define schemas ``` Things to know: - Compilation uses `new Function`. Global mode is automatically disabled when `z.config({ jitless: true })` is set (e.g. CSP environments); calling `z.compile()` directly is an explicit opt-in. - Schemas with async refinements or transforms can't be compiled, and neither can a few other constructs. That is not an error: `z.compile()` hands the schema back unchanged and it keeps using the regular parser, exactly as global mode leaves it. Pass `{ strict: true }` to throw `ZodCompileAsyncError` / `ZodCompileUnsupportedError` instead. - On invalid input, refinements and transforms may run twice (fast path, then fallback). - Deriving a new schema from a compiled one (`.refine()`, `.extend()`, etc.) returns an uncompiled schema — compile the final schema. See [`compile` docs](https://zod.dev/compile) for details. ### Handling errors When validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues. ```ts try { Player.parse({ username: 42, xp: "100" }); } catch (err) { if (err instanceof z.ZodError) { err.issues; /* [ { expected: 'string', code: 'invalid_type', path: [ 'username' ], message: 'Invalid input: expected string, received number' }, { expected: 'number', code: 'invalid_type', path: [ 'xp' ], message: 'Invalid input: expected number, received string' } ] */ } } ``` To avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently. ```ts const result = Player.safeParse({ username: 42, xp: "100" }); if (!result.success) { result.error; // ZodError instance } else { result.data; // { username: string; xp: number } } ``` **Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.safeParseAsync()` method instead. ```ts const schema = z.string().refine(async (val) => val.length <= 8); await schema.safeParseAsync("hello"); // => { success: true; data: "hello" } ``` ### Inferring types Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like. ```ts const Player = z.object({ username: z.string(), xp: z.number(), }); // extract the inferred type type Player = z.infer; // use it in your code const player: Player = { username: "billie", xp: 100 }; ``` In some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently: ```ts const mySchema = z.string().transform((val) => val.length); type MySchemaIn = z.input; // => string type MySchemaOut = z.output; // equivalent to z.infer // number ``` --- _Source: https://npm.io/package/zod · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._