---
id: phantom-types
version: "3.0.2"
license: BSD-3-Clause
license_treatment: permissive
maintenance: aging
---

# phantom-types — Phantom types for Python

License: permissive · Maintenance: aging · Downloads: 79.5K/mo

## What it is and what it does

Phantom types let you attach runtime predicates to Python types so that illegal states become unrepresentable at both the type-checking and runtime levels. Instead of validating data after parsing (shotgun parsing), you create a phantom type—a subclass of a base type like `str` with a predicate—and parse data into that type upfront. The type checker then treats the result as proven to satisfy the predicate, and runtime validators like typeguard or beartype can enforce the same constraint at call boundaries.

The package integrates with pydantic for schema generation and validation, works with static type checkers like mypy, and supports optional extras for datetime, phone number, and hypothesis-based testing. It requires Python 3.9+ and depends on typeguard, typing-extensions, and numerary at runtime.

Use it for:

- Enforce string constraints (e.g., non-empty, from a fixed set) at the type level so functions can assume preconditions without defensive checks.
- Combine with pydantic models to validate and document API request/response schemas with phantom type predicates.
- Use with beartype or typeguard to add runtime pre- and post-condition checking to functions without explicit guard clauses.
- Parse and validate user input once at the boundary, then pass phantom-typed values through your codebase with static proof of validity.
- Generate JSONSchema from pydantic models that include phantom types, automatically documenting constraints in API specs.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Phantom types enable you to create type-safe wrappers around base types (like strings or integers) with runtime predicates, allowing static type checkers and runtime validators to enforce constraints without shotgun parsing.

Yes, if you want to move validation earlier in your pipeline and leverage static type checking to prevent invalid states. The package is stable (Production/Stable classifier), has low install friction, and works well with pydantic and runtime type checkers. The 656-day gap since last release is a minor concern for long-term maintenance, but the repository remains active and there are no known vulnerabilities. Install it if your codebase values type safety and parse-don't-validate patterns.

## Install

pip install phantom-types
uv add phantom-types
poetry add phantom-types

## Installing phantom-types

Before you install: Low install friction; pure Python wheel with three runtime dependencies (typeguard, typing-extensions, numerary). Repository shows aging maintenance—last release was 656 days ago—but the project remains active with recent commits and no archived status.

License in practice: BSD-3-Clause (permissive) allows commercial use, modification, and distribution with minimal restrictions, making it suitable for most projects.

Quickstart:

pip install phantom-types

from phantom import Phantom
from phantom.predicates.collection import contained

class Name(str, Phantom, predicate=contained({"Jane", "Joe"})): ...

name = Name.parse("Jane")
print(f"Valid: {name}")

Requires Python 3.9 or later; optional extras (pydantic, hypothesis, dateutil, phonenumbers) require those packages to be installed separately.

Verify before relying:

- Whether runtime validation overhead is acceptable for performance-critical code paths.
- How well phantom types integrate with type checkers other than mypy (e.g., pyright, pyre).
- Whether the 656-day gap since last release indicates active maintenance or dormancy.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 79.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

phantom types python, type-safe validation predicates, parse don't validate, runtime type constraints, illegal states unrepresentable, pydantic type validation, static type checking guards, type-safety, validation, pydantic-compatible

[View on SkillFed](https://skillfed.io/packages/phantom-types) · [View on PyPI](https://pypi.org/project/phantom-types/)