{"id":7748,"library":"sqids","title":"Sqids Python","description":"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.","status":"active","version":"0.5.2","language":"en","source_language":"en","source_url":"https://github.com/sqids/sqids-python","tags":["id generation","short ids","url-safe","encoding","decoding","numbers"],"install":[{"cmd":"pip install sqids","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"Sqids","correct":"from sqids import Sqids"}],"quickstart":{"code":"from sqids import Sqids\n\nsqids = Sqids()\n\n# Encode numbers into a Sqid\nnumbers_to_encode = [1, 2, 3]\nid = sqids.encode(numbers_to_encode)\nprint(f\"Encoded ID: {id}\") # Example: 86Rf07\n\n# Decode a Sqid back into numbers\ndecoded_numbers = sqids.decode(id)\nprint(f\"Decoded numbers: {decoded_numbers}\") # Example: [1, 2, 3]\n\n# Enforce a minimum length for the ID\nsqids_min_length = Sqids(min_length=10)\nid_padded = sqids_min_length.encode([1, 2, 3])\nprint(f\"Padded ID: {id_padded}\") # Example: 86Rf07xd4z","lang":"python","description":"Initializes the Sqids encoder/decoder and demonstrates basic encoding and decoding of numbers, as well as enforcing a minimum ID length."},"warnings":[{"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.","message":"Due 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":"0.3.0 and later"},{"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.","message":"Sqids 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"0.5.0 and later"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","cause":"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.","error":"TypeError: 'list' object cannot be interpreted as an integer"},{"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.","cause":"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.","error":"ValueError: alphabet cannot contain multibyte characters"}]}