Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python None Type: Behavior, Pitfalls, and Best Practices

Understand Python's None type: singleton behavior, is None comparisons, Optional type hints, and common pitfalls like mutable default arguments.

~4 min readPython
#None#Python#Type Hints#Optional
Diagram showing Python None as a singleton object with identity checks and type hints.

In Python, None is a singleton object of type NoneType and represents the absence of a value. It is a fundamental part of the language, but its behavior often leads to subtle bugs. This article explains how None works, how to use it correctly in comparisons and type hints, and where it commonly trips up developers.

What None Is in Python

None is a singleton object of type NoneType. There is exactly one instance of None in any running Python process, and every reference to None points to that same object. You can verify this with the built-in id() function:

python
print(id(None)) # e.g., 140734982843328 print(id(None)) # same value

The fact that None is a singleton matters because it allows you to use identity checks (is None) instead of equality checks (== None). Identity checks compare object identity, which is semantically correct for a singleton and avoids invoking __eq__.

None is often used to indicate that a variable or function result has no meaningful value. It is the default return value for functions that do not explicitly return anything:

python
def do_nothing(): pass result = do_nothing() print(result) # None

How None Behaves in Comparisons and Boolean Contexts

When checking whether a value is None, use is rather than ==. While None == None is True, the equality operator can be overridden by custom classes, leading to unexpected results:

python
class Weird: def __eq__(self, other): return True print(Weird() == None) # True, but the object is not None print(Weird() is None) # False

Using is None is also faster because it does not invoke any __eq__ method. In boolean contexts, None is falsy, so if not value treats None the same as 0, False, and empty containers. This can hide bugs when a variable might legitimately be 0 or an empty string but not None:

python
def process(value): if not value: print('No value') else: print('Processing') process(None) # No value process(0) # No value (but 0 might be valid) process('') # No value (but empty string might be valid)

If you need to distinguish None from other falsy values, use an explicit is None check.

Using None in Function Returns and Default Arguments

A common pattern is to return None to signal that a function could not produce a result. For example, a lookup function might return None when a key is missing:

python
def find_user(database, user_id): if user_id in database: return database[user_id] return None

Callers must then check for None before using the result. This is straightforward, but it becomes error-prone when the function can also return other falsy values.

A more subtle issue is using None as a default argument. The classic pitfall is a mutable default that is shared across calls:

python
def add_item(item, items=[]): items.append(item) return items print(add_item(1)) # [1] print(add_item(2)) # [1, 2] # unexpected!

The default list is created once when the function is defined, not on each call. The standard fix is to use None as the default and create a new list inside the function:

python
def add_item(item, items=None): if items is None: items = [] items.append(item) return items print(add_item(1)) # [1] print(add_item(2)) # [2]

This pattern is idiomatic because None is immutable and cannot be accidentally modified.

Type Hints: Optional and None

In modern Python, you can annotate that a variable or parameter may be None using Optional[T] from typing or the union syntax T | None (Python 3.10+). This makes the intent explicit and helps static type checkers catch errors.

python
from typing import Optional def find_user(user_id: int) -> Optional[dict]: ... # Python 3.10+ equivalent: def find_user_new(user_id: int) -> dict | None: ...

When you use Optional, you signal to readers and tools that the return value can be None. A type checker will then require callers to handle the None case before using the result, preventing AttributeError at runtime.

Using Optional does not mean an argument can be omitted. In the following example, name can be omitted only because it has a default value; the annotation says the value can be None:

python
def greet(name: Optional[str] = None): if name is None: name = 'world' print(f'Hello, {name}!')

The distinction is important: Optional describes the type of the value, not whether the argument can be omitted. In this example, the default value is what allows greet() to be called without an argument.

Common Pitfalls with None

Checking for None with ==

As mentioned, == None can be overridden and is slower. Use is None for singleton checks.

Using or to Provide Defaults

A common idiom is value = input or default. This works when input is None, but it also replaces other falsy values like 0, False, and empty strings. If those are valid inputs, use an explicit is None check:

python
value = input if input is not None else default

None in List Comprehensions and Filters

When filtering out None values, filter(None, iterable) removes all falsy values, not just None. To remove only None, use a comprehension with is not None:

python
data = [1, None, 0, '', 2] cleaned = [x for x in data if x is not None] # [1, 0, '', 2]

None in JSON Serialization

None serializes to null in JSON, and null becomes None when parsed. This is usually intuitive. If you need to know whether a JSON field was absent rather than explicitly null, check key presence before parsing, because None/null alone does not record that distinction.

Performance and Memory Characteristics

Because None is a singleton, referencing it does not allocate new memory. Every use of None points to the same object, so there is no overhead from object creation. Using is None also avoids invoking __eq__, which can matter in hot paths, though for most applications the difference is negligible.

Another performance consideration is that None is often used as a sentinel to indicate missing data. If you frequently check for None in large data structures, using is None avoids the overhead of equality checks and is more readable.

Handling None in Data Structures and APIs

When designing APIs, decide whether None is a valid input or output. If a function accepts None to mean 'no value', document it clearly. In data structures, None can be used as a placeholder, but be aware that it is falsy and can interfere with boolean logic.

Consider using a sentinel object instead of None when you need to distinguish 'missing' from 'explicitly set to None'. For example, in a configuration system:

python
MISSING = object() def get_setting(settings, key, default=MISSING): if key in settings: return settings[key] if default is MISSING: raise KeyError(key) return default

This pattern avoids ambiguity when a setting can legitimately be None. The sentinel is a unique object, so is checks work reliably.

Finally, when working with third-party libraries, check their documentation for how they use None. Some libraries return None to indicate an error, while others raise exceptions. Knowing the convention prevents silent failures.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.