---
id: timeflake
version: "0.4.3"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# timeflake — Timeflake is a 128-bit, roughly-ordered, URL-safe UUID. Inspired by Twitter's Snowflake, Instagram's ID and Firebase's PushID.

License: permissive · Maintenance: dormant · Downloads: 190.4K/mo

## What it is and what it does

Timeflake is a 128-bit unique identifier that combines a 48-bit millisecond timestamp with an 80-bit cryptographically random component, designed to be both sortable and collision-resistant. Unlike UUID v1 (which leaks network info) or UUID v4 (which is random and fragments database indices), Timeflake orders by time in its most significant bits, keeping database indices compact and fast while remaining unpredictable within each millisecond.

The package provides multiple encodings—128-bit unsigned int, hex, URL-safe base62 (22 chars), and raw bytes—and is fully compatible with Python's standard uuid.UUID type. It includes optional extensions for Django ORM and Peewee, making it practical for use as a primary key in relational databases. No external dependencies are required.

Use it for:

- Use as a primary key in MySQL, Postgres, or SQLite3 to maintain insertion order and avoid index fragmentation.
- Generate unpredictable but sortable IDs for URLs and APIs where auto-increment integers are too predictable.
- Create distributed IDs across multiple machines without coordination or a centralized ID service.
- Replace UUID v4 in applications where both randomness and temporal ordering improve query performance.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Generates 128-bit, time-ordered, URL-safe unique identifiers (UUIDs) with millisecond-precision timestamps and cryptographic randomness, compatible with standard uuid.UUID.

Yes, if you need sortable, collision-resistant IDs for databases or URLs and want zero external dependencies. The library is stable and well-tested, but note that maintenance is dormant (last update 2023-09-01). Not suitable for security-sensitive use (password tokens, API keys); use Python's secrets module for those. Be aware that time-encoded IDs can leak privacy information about when and where content was created.

## Install

pip install timeflake
uv add timeflake
poetry add timeflake

## Installing timeflake

Before you install: Low install friction; pure Python with no runtime dependencies. Dormant maintenance (last commit 2023-09-01, 1078 days ago) but stable and archived repository shows no active development planned.

License in practice: MIT license permits commercial and private use with minimal restrictions; attribution required but no copyleft obligations.

Quickstart:

import timeflake

# Create a random Timeflake
flake = timeflake.random()
print(flake.base62)  # '00mx79Rjxvfgr8qat2CeQDs'
print(flake.timestamp)  # 1579091935216

# Parse existing flake
flake = timeflake.parse(from_base62='0002HCZffkHWhKPVdXxs0YH')

Verify before relying:

- Whether the 2^80 random bits per millisecond provide sufficient collision avoidance for your specific throughput and scale requirements.
- Current maintenance status and whether dormancy affects production readiness for your use case.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 190.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

time-ordered UUID generator, sortable unique ID library, snowflake-like ID generation, database-friendly UUID, URL-safe unique identifier, K-sortable ID, distributed ID generation, uuid-generation, distributed-systems, database-optimization

[View on SkillFed](https://skillfed.io/packages/timeflake) · [View on PyPI](https://pypi.org/project/timeflake/)