sqids

library0.5.2pypypi✓ verified 84d ago

Sqids (pronounced "squids") is a small, active, and community-maintained Python library that generates short, unique, and URL-safe IDs from non-negative numbers. It's commonly used for link shortening, generating IDs for public URLs or internal systems, and decoding for quicker database lookups. The current version is 0.5.2, and it follows a regular release cadence with ongoing development across various language ports.

serialization http-networking

pip install sqids

package ↗homepage ↗

INSTALL

IMPORT

SIG · SQIDS

sqids

serializationpythonv0.5.2

Install

1.7s avg

Import

11ms

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 v0.5.2 · 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.920 runs

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

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.009s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

Sqids

✓ from sqids import Sqids

Initializes the Sqids encoder/decoder and demonstrates basic encoding and decoding of numbers, as well as enforcing a minimum ID length.

from sqids import Sqids sqids = Sqids() # Encode numbers into a Sqid numbers_to_encode = [1, 2, 3] id = sqids.encode(numbers_to_encode) print(f"Encoded ID: {id}") # Example: 86Rf07 # Decode a Sqid back into numbers decoded_numbers = sqids.decode(id) print(f"Decoded numbers: {decoded_numbers}") # Example: [1, 2, 3] # Enforce a minimum length for the ID sqids_min_length = Sqids(min_length=10) id_padded = sqids_min_length.encode([1, 2, 3]) print(f"Padded ID: {id_padded}") # Example: 86Rf07xd4z

Debug

Known issues

gotchaDue to the algorithm's design, multiple distinct IDs might decode back into the same sequence of numbers. If canonical IDs are critical for your application, you must manually re-encode decoded numbers and verify that the newly generated ID matches the original.

fix

After decoding an ID, re-encode the resulting numbers and compare the new ID with the original to ensure canonical representation if required by your application logic.

affects: All versions

breakingVersion 0.3.0 introduced significant breaking changes, primarily an algorithm fine-tuning that causes IDs generated from the same inputs to change. Additionally, the `min_length` upper limit increased to 255, `min_value()` and `max_value()` functions were removed, and the minimum alphabet length changed from 5 to 3. The alphabet can no longer contain multibyte characters.

fix

If upgrading from versions prior to 0.3.0, be aware that existing Sqids will no longer decode to their original numbers using the new algorithm, or vice-versa. Update any stored IDs or decoding logic accordingly. Review the changelog for specific parameter and function changes.

affects: 0.3.0 and later

gotchaSqids is not an encryption library and should not be used for sensitive data. Generated IDs can be easily decoded back into their original numbers, which could inadvertently reveal information such as user counts if used for user IDs.

fix

Avoid using Sqids for any data that requires cryptographic security or where the underlying numerical values must remain confidential. Use dedicated encryption libraries for sensitive data.

affects: All versions

gotchaFor optimal performance, especially with blocklist checks, it is highly recommended to instantiate the `Sqids` class once and reuse that instance throughout your application. Version 0.5.0 improved encoding speed by ~85% but requires more calculation during instantiation.

fix

Instantiate `Sqids()` at the application's startup or as a singleton, and pass the same instance to all parts of your code that need to encode or decode IDs.

affects: 0.5.0 and later

Errors

Common errors & fixes

TypeError: 'list' object cannot be interpreted as an integer

The `encode` method expects a sequence of non-negative integers (e.g., `[1, 2, 3]`), but a single integer was passed without being wrapped in a list or tuple. This error is not specific to Sqids but a common Python mistake.

fix

Ensure that the numbers passed to `sqids.encode()` are always within a list or tuple, even if it's a single number. For example, `sqids.encode([123])` instead of `sqids.encode(123)`.

ValueError: alphabet cannot contain multibyte characters

Attempting to initialize `Sqids` with a custom alphabet containing characters that are not single-byte (e.g., emojis or certain Unicode characters). This restriction was introduced in v0.3.0.

fix

When defining a custom `alphabet`, ensure all characters are single-byte ASCII compatible. Remove any emojis or multi-byte Unicode characters from the alphabet string.

Upgrade

Version history

0.5.2latest on PyPI · released May 13, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://sqids.org/python ↗