A high-performance UUID v7 generation library implemented in C with Python bindings. The PyPI package is fastuuid7; the import package is uuidv7.

• Fast UUID v7 generation using C implementation
• RFC 9562 compliant UUID v7 format
• Python 3.8+ support
• Thread-safe implementation
• uuid.uuid7()-compatible API returning uuid.UUID
• High Performance: See Performance Benchmarks section below
• Usage Examples: See Examples section and examples/ directory

uv pip install fastuuid7

pip install fastuuid7

git clone https://github.com/nekrasovp/uuidv7.git
cd uuidv7
uv pip install -e .

from uuidv7 import uuid7

# Generate a UUID v7 (matches Python's uuid.uuid7() API)
u = uuid7()
print(u)        # e.g., 018f1234-5678-7abc-def0-123456789abc
print(repr(u))  # e.g., UUID('018f1234-5678-7abc-def0-123456789abc')
print(u.time)   # Unix timestamp in milliseconds

Note: Since 0.2.0, uuid7() returns a uuid.UUID object, matching Python's built-in uuid.uuid7() function available in Python 3.14+. Use str(uuid7()) when a string is needed. See Python documentation for details.

For performance-critical code that does not need a uuid.UUID object:

from uuidv7 import uuid7_bytes, uuid7_str

uuid_text = uuid7_str()
uuid_raw = uuid7_bytes()

uuid7() remains the compatibility API. uuid7_str() and uuid7_bytes() are explicit fast paths.

For more detailed usage examples, see the examples/ directory:

• Basic Usage - Simple UUID generation, validation, and performance demo
• Batch Generation - High-throughput UUID generation and uniqueness verification
• Database Usage - Using UUID v7 as primary keys with time-ordered records

Quick Start:

# Install the package first (required)
uv pip install -e .

# Run examples using python -m (recommended)
python -m examples.basic_usage
python -m examples.batch_generation
python -m examples.database_usage

# Or using uv run
uv run python -m examples.basic_usage

See the examples README for more details.

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

# Using pytest
uv run pytest

# Using uv
uv run pytest tests/

# Run ruff linter
uv run ruff check .

# Run ruff formatter
uv run ruff format .

# Fix auto-fixable issues
uv run ruff check --fix .

# Build wheel
uv build

# Build source distribution
uv build --sdist

# Run performance benchmarks comparing different implementations
python benchmarks/benchmark.py

# Or using uv
uv run python benchmarks/benchmark.py

Run benchmarks before making speed claims:

python benchmarks/benchmark.py --output benchmark-results.md
python benchmarks/clock_sources.py --output clock-source-results.md

The benchmark report includes OS, CPU, Python version, package versions, iterations, UUIDs/second, and ns/op for:

• uuidv7.uuid7() returning uuid.UUID
• uuidv7.uuid7_str()
• uuidv7.uuid7_bytes()
• str(uuidv7.uuid7())
• Python stdlib uuid.uuid7() when available
• published fastuuid7==0.1.0 in an isolated temporary environment
• optional competitors when installed: uuid-utils, fastuuidv7, and uuid7

Final release-check benchmark for 0.2.0 on GitHub Actions Ubuntu, x86_64, CPython 3.14.5:

Optional competitor comparison from the release benchmark pass on Linux x86_64, CPython 3.12.3:

Clock-source benchmark from the final release-check CI run:

This project uses GitHub Actions for continuous integration and deployment:

• CI Pipeline (.github/workflows/ci.yml):

  • Runs tests on Python 3.8 through 3.14
  • Runs linting with ruff
  • Builds the package to verify it compiles correctly
  • Triggers on push and pull requests

• Wheel Pipeline (.github/workflows/wheels.yml):

  • Builds wheels with cibuildwheel for Linux, macOS, and Windows
  • Verifies installed wheels can import uuidv7 and generate UUIDv7 values

• Publish Pipeline (.github/workflows/publish.yml):

  • Automatically publishes to PyPI when a new release is created
  • Builds platform wheels with cibuildwheel plus an sdist before publishing
  • Uses trusted publishing (no API tokens required)
  • Can be manually triggered via workflow_dispatch, but GitHub Releases are the recommended release path

1. Run tests, builds, and benchmarks.
2. Review benchmark results and decide whether optimization is needed.
3. Create a new GitHub Release.
4. The workflow will automatically build and publish to PyPI.

MIT License - see LICENSE file for details.

Pavel Nekrasov