The two concepts aren't related any more than any other type-related concepts.

In short, a TypeVar is a variable you can use in type signatures so you can refer to the same unspecified type more than once, while a NewType is used to tell the type checker that some values should be treated as their own type.

Type Variables

To simplify, type variables let you refer to the same type more than once without specifying exactly which type it is.

In a definition, a single type variable always takes the same value.

# (This code will type check, but it won't run.)
from typing import TypeVar, Generic

# Two type variables, named T and R
T = TypeVar('T')
R = TypeVar('R')

# Put in a list of Ts and get out one T
def get_one(x: list[T]) -> T: ...

# Put in a T and an R, get back an R and a T
def swap(x: T, y: R) -> tuple[R, T]:
    return y, x

# A simple generic class that holds a value of type T
class ValueHolder(Generic[T]):
    def __init__(self, value: T):
        self.value = value
    def get(self) -> T:
        return self.value

x: ValueHolder[int] = ValueHolder(123)
y: ValueHolder[str] = ValueHolder('abc')

Without type variables, there wouldn't be a good way to declare the type of get_one or ValueHolder.get.

There are a few other options on TypeVar. You can restrict the possible values by passing in more types (e.g. TypeVar(name, int, str)), or you can give an upper bound so every value of the type variable must be a subtype of that type (e.g. TypeVar(name, bound=int)).

Additionally, you can decide whether a type variable is covariant, contravariant, or neither when you declare it. This essentially decides when subclasses or superclasses can be used in place of a generic type. PEP 484 describes these concepts in more detail, and refers to additional resources.

Addendum: Python 3.12 generic parameter lists

Starting in Python 3.12, the following syntax has been available to declare type variables.

def get_oneT -> T: ...

def swapT, R -> tuple[R, T]: ...

class ValueHolder[T]:
    def __init__(self, value: T): ...
    def get(self) -> T: ...

These declarations are equivalent to those above, but now the type variables are only defined in type signatures within their functions/classes, rather than being stored in regular Python variables. The Python 3.12 release notes contain a summary, as well as links to more-detailed documentation.

NewType

A NewType is for when you want to declare a distinct type without actually doing the work of creating a new type or worry about the overhead of creating new class instances.

In the type checker, NewType('Name', int) creates a subclass of int named "Name."

At runtime, NewType('Name', int) is not a class at all; it is actually the identity function, so x is NewType('Name', int)(x) is always true.

from typing import NewType

UserId = NewType('UserId', int)

def get_user(x: UserId): ...

get_user(UserId(123456)) # this is fine
get_user(123456) # that's an int, not a UserId

UserId(123456) + 123456 # fine, because UserId is a subclass of int

To the type checker, UserId looks something like this:

class UserId(int): pass

But at runtime, UserId is basically just this:

def UserId(x): return x

There's almost nothing more than that to a NewType at runtime. In Python 3.8.1, its implementation was almost exactly as follows:

def NewType(name, type_):
    def identity(x):
        return x
    identity.__name__ = name
    return identity
Answer from jirassimok on Stack Overflow
🌐
GitHub
github.com › python › typing › issues › 189
Add NewType() to create simple unique types with zero runtime overhead · Issue #189 · python/typing
December 29, 2015 - The description is best gleaned from the following mypy issue: python/mypy#1284 (comment) and following. We're going with option (A). Really brief example: from typing import NewType UserId = NewType('UserId', int) Now to the type checke...
Author   gvanrossum
🌐
Asyncmove
py-nt.asyncmove.com
python-newtype
python-newtype is unique in its implementation of the "new type" concept from type theory. The key feature is its ability to maintain subtype relationships through method calls and provide robust type validation.
Discussions

python - What is the difference between TypeVar and NewType? - Stack Overflow
TypeVar and NewType seem related but I'm not sure when I'm supposed to use each or what the difference is at runtime and statically. More on stackoverflow.com
🌐 stackoverflow.com
Introduce new syntax to create `NewType` - Ideas - Discussions on Python.org
With PEP 695 accepted in Python 3.12, the soft keyword type can be used to create type aliases. # Old: from typing import TypeAlias Point: TypeAlias = tuple[float, float] # New: type Point = tuple[float, float] However, the current way to create NewTypes involves importing from the typing module, ... More on discuss.python.org
🌐 discuss.python.org
2
October 11, 2023
Introduction to a new runtime Python typing library - `python-newtype`! - Typing - Discussions on Python.org
🚀 Hey everyone! I’m beyond excited to share python-newtype, a new Python C-extension library I’ve been working on that makes Domain-Driven Development (DDD) not only easier but also super fast! 🐍⚡ Here’s what makes python-newtype stand out: It’s built with a C-extension under ... More on discuss.python.org
🌐 discuss.python.org
5
December 13, 2024
Should I use a type alias or typing.NewType?
You could create a proper Matrix class More on reddit.com
🌐 r/learnpython
6
1
April 10, 2021
🌐
Python.org
discuss.python.org › ideas
Structural Pattern Matching - Add support for `typing.NewType` and `typing.TypeAliasType` - Ideas - Discussions on Python.org
July 2, 2025 - The Problem typing.NewType is here to remove type confusion between string types, string types, string types, and string types [1], and only a few of them have strictly-typed counterparts (like pathlib.Path), as well as other similar cases. ...
🌐
X
x.com › alighodsi
Ali Ghodsi (@alighodsi) / X
January 15, 2010 - We’ve detected that JavaScript is disabled in this browser. Please enable JavaScript or switch to a supported browser to continue using x.com. You can see a list of supported browsers in our Help Center · By signing up, you agree to the Terms of Service and Privacy Policy, including Cookie Use
🌐
Chronicle of Higher Education
jobs.chronicle.com › job › 37960108 › research-associate-advanced-core-for-microscope-engineering
Research Associate - Advanced Core for Microscope ...
5 days ago - Explore thousands of faculty, administrative, and executive positions on our job board for higher education professionals. While you're there, create a job alert and upload your resume.
🌐
Python documentation
docs.python.org › 3 › library › typing.html
typing — Support for type hints
3 weeks ago - Doing Derived = NewType('Derived', Original) will make the static type checker treat Derived as a subclass of Original, which means a value of type Original cannot be used in places where a value of type Derived is expected.
Find elsewhere
Top answer
1 of 2
222

The two concepts aren't related any more than any other type-related concepts.

In short, a TypeVar is a variable you can use in type signatures so you can refer to the same unspecified type more than once, while a NewType is used to tell the type checker that some values should be treated as their own type.

Type Variables

To simplify, type variables let you refer to the same type more than once without specifying exactly which type it is.

In a definition, a single type variable always takes the same value.

# (This code will type check, but it won't run.)
from typing import TypeVar, Generic

# Two type variables, named T and R
T = TypeVar('T')
R = TypeVar('R')

# Put in a list of Ts and get out one T
def get_one(x: list[T]) -> T: ...

# Put in a T and an R, get back an R and a T
def swap(x: T, y: R) -> tuple[R, T]:
    return y, x

# A simple generic class that holds a value of type T
class ValueHolder(Generic[T]):
    def __init__(self, value: T):
        self.value = value
    def get(self) -> T:
        return self.value

x: ValueHolder[int] = ValueHolder(123)
y: ValueHolder[str] = ValueHolder('abc')

Without type variables, there wouldn't be a good way to declare the type of get_one or ValueHolder.get.

There are a few other options on TypeVar. You can restrict the possible values by passing in more types (e.g. TypeVar(name, int, str)), or you can give an upper bound so every value of the type variable must be a subtype of that type (e.g. TypeVar(name, bound=int)).

Additionally, you can decide whether a type variable is covariant, contravariant, or neither when you declare it. This essentially decides when subclasses or superclasses can be used in place of a generic type. PEP 484 describes these concepts in more detail, and refers to additional resources.

Addendum: Python 3.12 generic parameter lists

Starting in Python 3.12, the following syntax has been available to declare type variables.

def get_oneT -> T: ...

def swapT, R -> tuple[R, T]: ...

class ValueHolder[T]:
    def __init__(self, value: T): ...
    def get(self) -> T: ...

These declarations are equivalent to those above, but now the type variables are only defined in type signatures within their functions/classes, rather than being stored in regular Python variables. The Python 3.12 release notes contain a summary, as well as links to more-detailed documentation.

NewType

A NewType is for when you want to declare a distinct type without actually doing the work of creating a new type or worry about the overhead of creating new class instances.

In the type checker, NewType('Name', int) creates a subclass of int named "Name."

At runtime, NewType('Name', int) is not a class at all; it is actually the identity function, so x is NewType('Name', int)(x) is always true.

from typing import NewType

UserId = NewType('UserId', int)

def get_user(x: UserId): ...

get_user(UserId(123456)) # this is fine
get_user(123456) # that's an int, not a UserId

UserId(123456) + 123456 # fine, because UserId is a subclass of int

To the type checker, UserId looks something like this:

class UserId(int): pass

But at runtime, UserId is basically just this:

def UserId(x): return x

There's almost nothing more than that to a NewType at runtime. In Python 3.8.1, its implementation was almost exactly as follows:

def NewType(name, type_):
    def identity(x):
        return x
    identity.__name__ = name
    return identity
2 of 2
0

NewType() accepts an unique type parameter. To specialize the function for different types for static typing, you only need a TypeVar here.

Example: Read https://dev.to/decorator_factory/typevars-explained-hmo

🌐
Python.org
discuss.python.org › ideas
Introduce new syntax to create `NewType` - Ideas - Discussions on Python.org
October 11, 2023 - With PEP 695 accepted in Python 3.12, the soft keyword type can be used to create type aliases. # Old: from typing import TypeAlias Point: TypeAlias = tuple[float, float] # New: type Point = tuple[float, float] However, the current way to create NewTypes involves importing from the typing module, and providing a name string, which is unintuitive: from typing import NewType OrderId = NewType("OrderId", int) Unlike type aliases, NewTypes don’t have first-class syntax support.
🌐
Inside Higher Ed
careers.insidehighered.com › job › 3475227 › research-associate-advanced-core-for-microscope-engineering
Research Associate - Advanced Core for Microscope Engineering - Philadelphia job with University of Pennsylvania | 3475227
Expertise is required in the specific area of physics, computer science, engineering or related field with at least 5 years of relevant experience;. PhD is required. Responsibilities may include designing and implementing optics hardware (ideally microscopes), leveraging Python and/or LabView, and use of digital and analog signal processing.
🌐
Python.org
discuss.python.org › typing
Introduction to a new runtime Python typing library - `python-newtype`! - Typing - Discussions on Python.org
December 13, 2024 - 🚀 Hey everyone! I’m beyond excited to share python-newtype, a new Python C-extension library I’ve been working on that makes Domain-Driven Development (DDD) not only easier but also super fast! 🐍⚡ Here’s what makes python-newtype stand out: It’s built with a C-extension under the hood, which means it’s optimized for performance.
🌐
Mypy
mypy.readthedocs.io › en › stable › more_types.html
More types - mypy 1.19.1 documentation
NewType lets you define a variant of a type that is treated as a separate type by mypy but is identical to the original type at runtime.
🌐
Reddit
reddit.com › r/learnpython › should i use a type alias or typing.newtype?
r/learnpython on Reddit: Should I use a type alias or typing.NewType?
April 10, 2021 -

I want to create a type for matrices. Should I use a type alias or typing.NewType?

Matrix = NewType('Matrix', List[List[int]]) or simply Matrix = List[List[int]] ?

🌐
Austin
austin.ky › blog › python-typing-newtype
Consider Python’s NewType Instead of an Alias
December 19, 2020 - Doing Derived = NewType('Derived', Original) will make the static type checker treat Derived as a subclass of Original, which means a value of type Original cannot be used in places where a value of type Derived is expected.
🌐
Python-future
python-future.org › _modules › future › utils.html
future.utils — Python-Future documentation
Navigation · index · modules · Python-Future documentation » · Module code » · future.utils · Source code for future.utils · """ A selection of cross-compatible functions for Python 2 and 3. This module exports useful functions for 2/3 compatible code: * bind_method: binds functions ...
🌐
Uqcloud
csse1001.uqcloud.net › 01B-arithmetic.html
Python as a Calculator
In this lecture we focus on what arithmetic expressions are legal in the Python language.
🌐
Berniepope
berniepope.id.au › assets › files › ImplementPythonInHaskell.pdf pdf
Implementing Python in Haskell, twice. Bernie Pope
April 24, 2014 - semantics (on paper) for Python bytecode. Then I came to my senses and started writing it · in Haskell · The interpreter is straightforward · data EvalState = EvalState · { evalState_objectID :: !ObjectID · , evalState_heap :: !Heap · , evalState_globals :: !Globals · , evalState_frameStack :: ![HeapObject] } newtype Eval a ·
🌐
GitHub
github.com › python › typing › issues › 746
repr of NewType · Issue #746 · python/typing
August 14, 2020 - Currently NewType has a rather unsatisfactory repr: from typing import NewType A = NewType("A", int) print(repr(A)) outputs: .new_type at MEMORYADDRESS&...
Author   hoodmane