Registry / data / fastwarc

fastwarc

JSON →
library1.0.7pypypi✓ verified 87d ago

FastWARC is a high-performance Python library for parsing WARC (Web ARChive) files, written in C++/Cython. It supports WARC/1.0 and WARC/1.1 streams with GZip and LZ4 compression, offering significant speed improvements over pure Python alternatives like WARCIO. FastWARC is part of the ChatNoir Resiliparse toolkit and is currently at version 0.16.0, with active development.

pip install fastwarc
INSTALL
IMPORT
SIG · FASTWARC
F
fastwarc
datapythonv1.0.7
Install
3.2s avg
Import
96ms
Disk
81MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.7 · 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
glibc
py 3.10
✕ build_error
✓ 3.68s
py 3.11
✕ build_error
✓ 3.64s
py 3.12
✕ build_error
✓ 2.78s
py 3.13
✕ build_error
✓ 2.83s
py 3.9
✕ build_error
✕ build_error
81MB installed
● package 81MB
Code
Verified usage

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

ArchiveIterator
from fastwarc.warc import ArchiveIterator
WarcRecord
from fastwarc.warc import WarcRecord
WarcRecordType
from fastwarc.warc import WarcRecordType

This quickstart demonstrates how to iterate through records in a WARC file using `ArchiveIterator`. It shows how to access record metadata like `record_id` and `url`, and how to read the content. For HTTP response records, it also shows how to access parsed HTTP headers. A dummy WARC file is created for the example to be runnable.

import os from fastwarc.warc import ArchiveIterator, WarcRecordType # Create a dummy WARC file for demonstration purposes dummy_warc_content = b'WARC/1.0\r\nWARC-Type: warcinfo\r\nWARC-Date: 2023-01-01T12:00:00Z\r\nWARC-Record-ID: <urn:uuid:example-warcinfo>\r\nContent-Length: 100\r\n\r\ninfo: This is a dummy WARC file created for FastWARC quickstart example.\n123456789012345678901234567890\r\nWARC/1.0\r\nWARC-Type: response\r\nWARC-Date: 2023-01-01T12:00:01Z\r\nWARC-Record-ID: <urn:uuid:example-response>\r\nWARC-Target-URI: http://example.com/\r\nContent-Length: 77\r\n\r\nHTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\nHello, FastWARC!\n' with open('example.warc', 'wb') as f: f.write(dummy_warc_content) warc_path = 'example.warc' if not os.path.exists(warc_path): print(f"Error: WARC file '{warc_path}' not found. Please ensure it exists.") else: try: # Iterate over WARC records, parsing HTTP for response records for record in ArchiveIterator(warc_path, parse_http=True): if record.record_type == WarcRecordType.warcinfo: print(f"WARC Info Record ID: {record.record_id}") print(f"Content: {record.reader.read().decode('utf-8').strip()}") elif record.record_type == WarcRecordType.response: print(f"\nResponse Record URL: {record.url}") if record.http_headers: print(f"HTTP Status: {record.http_headers.status_code}") print(f"Payload: {record.reader.read().decode('utf-8').strip()}") except Exception as e: print(f"An error occurred during WARC processing: {e}") finally: # Clean up the dummy WARC file os.remove(warc_path)
Debug
Known issues
gotchaFastWARC is not a drop-in replacement for WARCIO. Its API is inspired by WARCIO but designed for performance, meaning direct migration may require code adjustments.
fix
Review FastWARC documentation for API differences when migrating from WARCIO.
affects: All versions
gotchaMalformed WARC records (e.g., missing Content-Length, non-standard line endings) in archives like ClueWeb can cause parsing issues. By default, `strict_mode=True` which may lead to early termination.
fix
Pass `strict_mode=False` to `ArchiveIterator` for more lenient parsing of non-compliant WARC files. Be aware this might affect how record boundaries are determined.
affects: All versions
gotchaAutomatic HTTP parsing (`parse_http=True`) can incur a performance overhead. If you only need WARC metadata or raw content and not parsed HTTP headers, this can be skipped.
fix
Set `parse_http=False` in the `ArchiveIterator` constructor. You can parse HTTP headers later on a per-record basis using `record.parse_http()` if needed.
affects: All versions
gotchaVerifying record digests (e.g., `record.verify_block_digest()`) creates an in-memory copy of the remaining record stream to preserve its contents for further processing. This can consume significant memory for very large records.
fix
For large records, ensure they fit into memory or set `consume=True` when calling digest verification methods if you do not need to preserve the stream contents for subsequent operations. This avoids creating a stream copy.
affects: All versions
breakingFastWARC explicitly does not support the legacy ARC (Archive Record) format for simplicity and performance reasons.
fix
If you require ARC format compatibility, you will need to use a different library such as WARCIO.
affects: All versions
gotchaPre-built Linux binaries are compiled on an older `manylinux` base system for compatibility, which may not offer optimal performance on modern systems.
fix
For the best performance on Linux, it is recommended to build FastWARC from source by installing build dependencies (`build-essential`, `python3-dev`, `zlib1g-dev`, `liblz4-dev`) and then using `pip install --no-binary fastwarc fastwarc`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fastwarc'
The fastwarc library is not installed in the current Python environment, or its installation failed due to missing C/Cython build dependencies.
fix
Install fastwarc using pip. If pre-built binaries are not available or fail, ensure build dependencies are installed for your operating system (e.g., `sudo apt install build-essential python3-dev zlib1g-dev liblz4-dev` on Ubuntu) and then run `pip install --no-binary fastwarc fastwarc` to build from source.
ImportError: cannot import name 'WarcReader' from 'fastwarc.warc'
Developers migrating from WARCIO (which has a `WarcReader` class) might attempt to import a non-existent class from `fastwarc`. FastWARC uses `ArchiveIterator` as its primary class for iterating WARC records.
fix
Replace `WarcReader` with `ArchiveIterator`. The correct import is `from fastwarc.warc import ArchiveIterator`.
AttributeError: 'WarcRecord' object has no attribute 'raw_stream'
This error occurs when attempting to access the `raw_stream` attribute on a `fastwarc.warc.WarcRecord` object, an attribute common in WARCIO's `ArcWarcRecord` but not present in FastWARC. FastWARC uses `record.reader` to access the payload stream.
fix
Access the record's payload stream using `record.reader` instead of `record.raw_stream`. For example, `payload_data = record.reader.read()` will read the body.
fastwarc.stream_io.FastWARCError: FastWARC stream error
This is a generic error raised by FastWARC indicating an issue during stream processing, often due to malformed WARC records, unexpected end-of-stream, or data corruption within the WARC file.
fix
Implement robust error handling by wrapping WARC processing in a `try...except fastwarc.stream_io.FastWARCError` block. For problematic WARC files (e.g., ClueWeb), consider initializing `ArchiveIterator` with `strict_mode=False` or `parse_http=False` to handle non-standard formats.
Upgrade
Version history
1.0.7latest on PyPI · released Jun 11, 2026
Audit
Dependencies
fsspecoptionalEnables reading WARC files from remote filesystems and URLs.
Agent activity
8 hits · last 30 days
node
8
Resources
fastwarc — pip install fastwarc · libregistry