Install & Compatibility
Where this runs
tested against v5.1.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
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Str
✓ from stringzilla import Str
Main string class for in-memory byte arrays.
File
✓ from stringzilla import File
Memory-maps files for immutable, shared access.
Strs
✓ from stringzilla import Strs
Class for collections of strings, similar to `list[str]`, used in split operations.
Demonstrates basic usage of `Str` for in-memory string operations and `File` for memory-mapped file handling, including length, substring checks, and finding substrings.
from stringzilla import Str, File
# Using Str for in-memory strings
text_str = Str('hello stringzilla and the world!')
print(f"Length of text_str: {len(text_str)}")
print(f"Does 'stringzilla' exist? {'stringzilla' in text_str}")
print(f"Index of 'world': {text_str.find('world')}")
# Example with File (requires a dummy file)
# To run this, create a file named 'example.txt' with some content
import os
with open('example.txt', 'w') as f:
f.write('This is a test file for StringZilla.\n')
f.write('It demonstrates memory-mapped file usage.')
file_str = File('example.txt')
print(f"Length of file_str: {len(file_str)}")
print(f"Does 'test file' exist? {'test file' in file_str}")
print(f"Lines in file_str: {len(file_str.splitlines())}")
# Clean up the dummy file
os.remove('example.txt')
null --version
Debug
Known issues
gotchaUsers often install `stringzilla` (the base package) but might expect parallel performance. For multi-CPU backends, `stringzillas-cpus` is required, and for Nvidia GPU, `stringzillas-cuda` must be installed separately. These are distinct packages, and `stringzilla` only provides serial algorithms.fixEnsure you install `stringzillas-cpus` or `stringzillas-cuda` if parallel processing is desired: `pip install stringzillas-cpus`.
affects: All versions
gotchaOptimal performance and certain advanced features (e.g., specific case-folding and case-insensitive search paths) heavily rely on modern CPU extensions like AVX-512, Arm Neon, or SVE. Running on older hardware or virtualized environments without these features may result in lower performance than expected or fallback to less optimized scalar implementations.fixConsult `stringzilla.__capabilities__` to understand the detected hardware features. Performance will scale with available SIMD instructions.
affects: All versions
gotchaThe `stringzillas` (parallel) components are explicitly noted as being in 'beta' and 'under active development, and are likely to break in subsequent releases'. Users of these parallel backends should anticipate potential API changes or breaking changes between minor versions.fixPin `stringzillas` versions carefully in production environments and review release notes for breaking changes upon upgrade.
affects: All `stringzillas` versions
gotchaStringZilla aims for full Unicode 17.0 compliance, particularly for case-folding and case-insensitive searches. Ensure that your input data is correctly encoded in UTF-8 to leverage these features accurately. Incorrect encodings can lead to unexpected search results or behavior.fixAlways provide UTF-8 encoded strings to StringZilla functions for full Unicode compliance. Use `str.encode('utf-8')` if necessary. affects: All versions
Upgrade
Version history
5.1.2latest on PyPI · released Aug 12, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.8 or newer.