hashids

library1.3.1pypypi✓ verified 23d ago

Hashids is a small library that generates short, unique, and non-sequential IDs from numbers. It's often used for obfuscating database IDs in URLs, tracking, or invitation codes, providing a user-friendly and URL-safe representation of integers without exposing their underlying numeric values. The current version is 1.3.1. It is mostly in maintenance mode, as a new version called Sqids is the recommended successor.

serialization auth-security

pip install hashids

package ↗homepage ↗

INSTALL

IMPORT

SIG · HASHIDS

hashids

serializationpythonv1.3.1

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Hashids

✓ from hashids import Hashids

✗ import hashids; hashids.Hashids()

While functional, directly importing `Hashids` is the idiomatic way to use the constructor.

This quickstart demonstrates how to initialize the `Hashids` class with a salt and minimum length, then encode single or multiple integers into a hashid string, and finally decode the hashid back to the original integers.

from hashids import Hashids # Instantiate with optional salt and minimum hash length for better obfuscation # Using a salt makes your hashes unique to your application. # min_length ensures all generated hashes are at least that long. # For production, consider getting the salt from environment variables. hashids = Hashids(salt="my-super-secret-salt-from-env", min_length=8) # Encode one or more integers into a hashid string id_to_encode = 12345 encoded_id = hashids.encode(id_to_encode) print(f"Encoded {id_to_encode}: {encoded_id}") multiple_ids_to_encode = (1, 2, 3) encoded_multiple = hashids.encode(*multiple_ids_to_encode) print(f"Encoded {multiple_ids_to_encode}: {encoded_multiple}") # Decode a hashid string back to its original integers (as a tuple) decoded_ints = hashids.decode(encoded_id) print(f"Decoded '{encoded_id}': {decoded_ints}") decoded_multiple = hashids.decode(encoded_multiple) print(f"Decoded '{encoded_multiple}': {decoded_multiple}")

Debug

Known issues

gotchaHashids is for obfuscation, not security or cryptography. It is reversible and should not be used for sensitive data, passwords, or any scenario requiring true cryptographic hashing.

fix

Always combine Hashids with proper authorization and never treat the generated IDs as secure tokens. For cryptographic needs, use libraries like `passlib` or `cryptography`.

affects: All versions

breakingThe default alphabet was changed in versions 1.0.0 and above. If you need compatibility with hashids.js v0.1.x, you must install hashids-python v0.8.4. For hashids.js v0.3.x+, use hashids-python v1.0.2+.

fix

Ensure your Python `hashids` version matches the expected JavaScript `hashids` version for cross-language compatibility. For new projects, stick to the latest versions.

affects: 1.0.0+

gotchaUsing a unique `salt` value is crucial. Without a salt (or with a commonly known one), different applications would generate the same hash for the same number, making it easy to guess or reverse.

fix

Always initialize `Hashids` with a strong, unique, and secret salt string. Ideally, retrieve this salt from environment variables or a secure configuration system.

affects: All versions

deprecatedThe original creator of Hashids has introduced an improved and rebranded library called 'Sqids'. While Hashids is still maintained, Sqids is the recommended successor for new projects, offering a simplified API, consistent output across languages, and clearer goals.

fix

For new projects, consider using 'Sqids' (pip install sqids) instead of 'Hashids'. For existing projects, be aware that Hashids is largely in maintenance mode.

affects: All versions

gotchaHashids does not prevent enumeration attacks on its own. While it obfuscates sequential IDs, if an attacker can simply increment/decrement the generated hash and get valid responses, it can still expose the total number of records or allow unauthorized access if not backed by proper authorization.

fix

Always implement robust authorization checks on your backend endpoints, regardless of whether you're using plain IDs or Hashids. Hashids is a layer of obfuscation, not a security control.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hashids'

The 'hashids' library has not been installed in the current Python environment.

fix

Install the library using pip:
```bash
pip install hashids
```

TypeError: an integer is required (got type str)

The `encode` method was called with a non-integer argument, but it expects only integers or floats (which are converted to integers).

fix

Ensure all arguments passed to `encode` are integers or floats:
```python
from hashids import Hashids
hashids = Hashids()
encoded_id = hashids.encode(123, 456)
# Floats are also accepted and truncated
encoded_float_id = hashids.encode(123.5, 456.7)
```

TypeError: 'int' object is not iterable

The `alphabet` parameter during Hashids initialization was provided with an integer, but it expects a string or another iterable containing the characters for the hash.

fix

Provide the `alphabet` as a string of unique characters:
```python
from hashids import Hashids
# Correct usage
hashids = Hashids(alphabet="abcdefghijklmnopqrstuvwxyz1234567890")
```

TypeError: can only concatenate tuple (not "int") to tuple

The `decode` method always returns a tuple of integers, but the code attempts to use this tuple directly as a single integer, leading to a type mismatch.

fix

Access the decoded integers from the tuple, either by unpacking it or by indexing:
```python
from hashids import Hashids
hashids = Hashids()
encoded_id = hashids.encode(123)

# Correct usage: unpack the tuple (for a single expected number)
decoded_number, = hashids.decode(encoded_id)
print(decoded_number + 1) # Example: 124

# Correct usage: access elements by index
decoded_numbers = hashids.decode(encoded_id)
print(decoded_numbers[0] + 1) # Example: 124
```

Upgrade

Version history

1.3.1latest on PyPI · released Jul 26, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/hashids/ ↗

homepagehttps://hashids.org/python/ ↗