pywb Web Archive Replay, Recording, and Configuration

What pywb Solves in Web Archive Operations

pywb addresses the operational gap between storing web captures in WARC form and presenting them through a usable web interface. It is aimed at archive operators, institutions running historical web collections, developers embedding replay capabilities, and services that need behavior comparable to traditional Wayback-style access. The README describes it as the foundation of Webrecorder while also presenting it as a generic toolkit used by other web archives.

The project covers both sides of an archiving workflow. On the read side, it replays archived content and rewrites links so navigation remains connected to captured material. On the write side, its Recorder component can create archives from the live web or from other archives. Warcserver, Recorder, and Rewriter are identified as standalone components, which gives an operator a more modular architecture than a simple collection viewer.

This is an infrastructure-level project rather than a desktop browser or a one-command crawler. Its scope includes dynamic multi-collection configuration, replay and recording, Memento API aggregation, proxy-mode recording and replay, access controls, localization, and UI customization. That breadth makes pywb relevant when the requirement extends beyond opening archived pages. It is a poorer fit when the only goal is manually reading WARC files or capturing a small site without deploying a configurable service.

pywb Replay and Recording Data Flow

The visible architecture separates archive acquisition, archive serving, and content rewriting. Recorder handles the creation of new web archives from live sites or other archives. Warcserver acts as the archive-access component. Rewriter changes archived content so its requests and navigation can be redirected into the replay system. The README also identifies `wombat.js` as a standalone, modular client-side rewriting system intended to handle many modern sites.

For replay, the logical flow begins with a request for an archived URL and continues through collection lookup and rewriting. The project supports a Memento API with aggregation and fallback chains across multiple remote and local archival sources. That mechanism matters for deployments that cannot treat one WARC store as the only possible answer. The README does not document availability guarantees or consistency rules across those sources, so operators should not assume that fallback removes the need for collection planning.

Recording can operate through the same broader toolkit, including HTTP/S proxy mode with a configurable certificate authority. Proxy mode brings certificate handling and network policy into the deployment boundary. The project also provides pluggable rewriters for different content types and added client-side replay as an option in 2.9 through `config.yaml`. Server-side and client-side rewriting are therefore real alternatives in approach. Server-side rewriting stays within the Python service path, while client-side replay delegates part of the adaptation to JavaScript running in the browser. The README provides no compatibility matrix establishing which archived sites work under each mode.

Installing pywb and Starting the Executable

For a deployment installation, the README directs Linux users to check for `python3-dev` first. On Debian-based systems, its documented installation command is:

sudo apt install python3-dev

This installs the development headers needed by the stated Linux installation path. If `python3-dev` is already present, this command is unnecessary.

Install pywb from the Python package index with:

pip install pywb

The README notes that `pip3` may be required depending on the Python installation. After installation, it states that either of these entry points can be run:

pywb

wayback

The README does not give the expected startup output or a complete first-run command that selects a configuration file. It directs users to the local or online documentation for current usage and configuration. Seeing the installed command resolve is therefore the first documented milestone, not confirmation of a usable collection.

For development from a local repository, the documented commands are:

git clone https://github.com/webrecorder/pywb

After changing into the cloned directory, an editable installation can be created with:

pip install -e .

The project recommends `tox --current-env` for tests after installing its test tooling, but that is a developer verification path rather than a first use of the replay application.

Collections, Docker Inputs, and Configuration Boundaries

The repository ships a `config.yaml`, a `sample_archive/` directory, and a `docker-compose.yaml`. The Compose service exposes host port 8080 on container port 8080. It mounts the local configuration file at `/webarchive/config.yaml` and the sample archive directory at `/webarchive/sample_archive/`. Those are concrete deployment inputs, although the README does not document the command used to start the Compose service or the URL path needed to browse the sample.

The Dockerfile uses `python:3.14-slim` by default through its `PYTHON` build argument. It installs `requirements.txt`, several additional Python packages, and pywb itself. The resulting image declares `/webarchive` as a volume, exposes port 8080, and mounts the Wayback application through `UWSGI_MOUNT`. This shows a server-oriented deployment with uWSGI rather than a simple development server.

Configuration is a meaningful responsibility. The README reports that collections can be updated without restarting pywb, but it does not include the relevant collection rules. It also identifies access control by URL prefix or exact match, embargo and HTTP-header controls, localization, themes, and replay UI customization. None of those features can be enabled accurately without the full configuration guide. The presence of a sample configuration file is useful, but it does not by itself establish production readiness.

The package also pins or constrains several dependencies, including `redis==2.10.6`, `pyOpenSSL<26.2`, and `fakeredis<1.0`. The comment for `pyOpenSSL` states that `certauth` uses an X509 method removed in version 26.2. This is a concrete upgrade constraint rather than a general maintenance warning.

Replay Failures, Recording Boundaries, and Tool Fit

The largest documented limitation is the absence of a complete configuration and first-use procedure in the README. pywb exposes the `pywb` and `wayback` commands, but the README does not state what output confirms a healthy service, how to register the sample archive, which replay route to open, or how to verify that recording produced a valid WARC. The linked online and local documentation fills that gap, but those pages are not reproduced in the repository excerpt.

Archive rewriting also has a browser and content boundary. pywb supports pluggable rewriters by content type and `wombat.js` for modern sites, but the README does not claim universal replay fidelity for JavaScript-heavy pages. “As accurately as possible” is the project’s stated goal, not a guarantee that every capture will reproduce its original behavior. Client-side replay adds a JavaScript dependency and can fail differently from server-side rewriting. The README provides no debugging procedure for failed scripts, blocked resources, mixed content, or certificate errors.

Proxy recording is another boundary. HTTP/S proxy mode requires certificate-authority handling, while the README does not document browser trust installation, proxy exclusions, or recovery from certificate failures. Deployments should therefore treat proxy configuration as an operational feature, not as default-on behavior.

pywb is also the wrong tool when a static WARC viewer would meet the requirement without recording, collections, proxy access, or service customization. Its component and configuration surface would add work that a simpler reader would not need. The README does not name a specific static viewer, so this article does not assert a named competitor or undocumented comparison.

Release Cadence, GPL-3.0, and Upgrade Work

The repository is not archived. Its last push was on 2026-10-17. Release records show v2.10.0 on 2026-09-22 and v2.11.0 Beta 1 on 2026-10-13. The sequence indicates recent release activity, but the newest listed build is explicitly a beta, so it should not be treated as interchangeable with the stable release without a separate compatibility decision.

The project is licensed under GPL-3.0. That identifier establishes the repository’s declared license, but this article does not interpret how it applies to a particular deployment or distribution arrangement. Organizations need to review `LICENSE`, `NOTICE`, bundled dependencies, and their own distribution model before adoption.

Upgrade cost is visible in several places. The requirements include exact and upper-bound constraints, so a rebuild can expose compatibility issues before deployment. The setup process in `setup.py` downloads `wabac.js` version 2.27.2 from jsDelivr unless the packaged service worker is already present and has the expected header. Packaging environments therefore need appropriate network access or a correctly prepared local copy. The Docker build also installs system and Python packages, meaning a container update is broader than changing application code.

The project’s modular design can make upgrades more targeted than an all-in-one application, but the README does not document supported upgrade paths between 2.10.0 and 2.11.0 Beta 1, configuration migrations, or rollback procedures. Those points require confirmation in `CHANGES.rst`, `RELEASING.md`, and the full documentation before production adoption.

Editorial conclusion

Adopt pywb when an archive service needs integrated replay, live recording, configurable collections, access controls, or both server-side and client-side rewriting. Do not choose it from the README alone if you require a documented first-run deployment or a turnkey crawler workflow. Verify first that `pywb` starts with the intended `config.yaml`, that required WARC data is mounted in the correct locations, and that the selected rewriting mode works with the archived content. The repository is not archived and its last push was on 2026-10-17, while v2.11.0 Beta 1 is newer than the stable v2.10.0 release.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. webrecorder/pywb on GitHub