Python hash() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Built-in

Definition

In Python, hash(obj) returns an integer that dicts and sets use to place and find keys quickly. The key rule is: objects that compare equal must have the same hash. That is why hash(1), hash(1.0), and hash(True) are all 1.

Only hashable (normally immutable) objects have a hash; lists, dicts, and sets are unhashable. For security, string and bytes hashes are randomized per process, so they differ between runs unless the PYTHONHASHSEED environment variable fixes them.

hash() is a built-in function: it lives in the builtins module, so it is always available without an import.

Syntax

Pass one hashable object.

python
value = hash(obj)
CallWhat it does
hash(42)Returns 42 (small ints hash to themselves).
hash(-1)Returns -2: -1 is reserved internally.
hash(1.0) == hash(1)True: equal numbers hash equally.
hash([1, 2])Raises TypeError: unhashable.

Never store string hashes or rely on them across runs; they change every time Python starts. Use hashlib for stable checksums.

Library declarations
python
hash(object, /)
# calls type(object).__hash__(object)

Parameters

ParameterDescription
objectRequired. A hashable object.

Return Value

Return ValueDescription
intThe hash value.

Python Examples

Example 1 — Hash Values of Numbers

Look at the hashes of a few numbers that CPython makes predictable.

python
print(hash(42))
print(hash(-1))
print(hash(1.0), hash(True))
print(hash(1) == hash(1.0) == hash(True))

How It Works

  1. Small ints. In CPython, a small int hashes to itself, so hash(42) is 42.
  2. The -1 exception. -1 signals an error inside CPython's C code, so hash(-1) is -2 instead.
  3. Equal across types. 1.0 and True equal 1, so they must hash to 1.
  4. The contract. Equal values always share a hash; that is what dicts rely on.

Example 2 — Why Equal Keys Find the Same Entry

Compare hashes of equal strings and tuples without printing them, and look up a dict with equal keys.

python
word = "python"
print(hash(word) == hash("py" + "thon"))

pair = (1, 2)
print(hash(pair) == hash((1, 2)))

names = {1: "one"}
print(names[1.0], names[True])

How It Works

  1. Compare, don't print. String hashes change between runs, but two equal strings in the same run always match.
  2. Tuples hash their items. Two tuples with equal items produce the same hash.
  3. Lookup by equal key. 1.0 and True equal 1 and hash the same, so they find the entry stored under 1.
  4. Run-to-run changes. Set PYTHONHASHSEED=0 only if you need reproducible string hashes, for example in tests.

Example 3 — Unhashable Lists and a Hashable Class

Try to hash a list, then make a class usable in sets with __eq__ and __hash__.

python
try:
    hash([1, 2])
except TypeError:
    print("lists are unhashable")


class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __eq__(self, other):
        return (self.x, self.y) == (other.x, other.y)

    def __hash__(self):
        return hash((self.x, self.y))


seen = {Point(1, 2), Point(1, 2), Point(3, 4)}
print(len(seen))
print(Point(1, 2) in seen)

How It Works

  1. Mutable means unhashable. A list could change after being stored, so it has no hash.
  2. Same fields for both. __eq__ and __hash__ use the same (x, y) tuple, keeping the contract.
  3. Duplicates merge. The two Point(1, 2) objects are equal, so the set keeps one of them.
  4. Lookups work. A brand-new Point(1, 2) is found in the set.

Frequently Asked Questions

It returns the integer hash that dicts and sets use to store and find keys quickly.
String and bytes hashes are randomized per process for security. Set PYTHONHASHSEED to make them reproducible.
CPython uses -1 internally as an error signal, so the hash of -1 is changed to -2.
Lists can change. If a list changed after being used as a key, its hash would no longer match. Use a tuple instead.
Define __hash__ returning hash() of the same fields used in __eq__, and keep those fields unchanged.

Next: help()

Show built-in documentation for an object.

help() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful