Install & Compatibility
Where this runs
tested against v0.7.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.150s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.144s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from mwparserfromhell import parse
✗ import mwparserfromhell
This quickstart demonstrates basic parsing of MediaWiki wikicode, extracting templates, their parameters, and headings using the `mwparserfromhell.parse()` function and `Wikicode` object's filter methods.
import mwparserfromhell
text = """I has a template! {{foo|bar|baz|eggs=spam}} \n== Heading ==\n[[File:Example.jpg|thumb|A caption.]] See it?"""
wikicode = mwparserfromhell.parse(text)
print(wikicode) # Outputs the original wikicode
# Filter for templates
templates = wikicode.filter_templates()
if templates:
template = templates[0]
print(f"Template name: {template.name}")
print(f"Template parameter '1': {template.get(1).value}")
print(f"Template parameter 'eggs': {template.get('eggs').value}")
# Filter for wikilinks (e.g., file captions are wikilinks)
wikilinks = wikicode.filter_wikilinks()
if wikilinks:
print(f"First wikilink: {wikilinks[0].title}")
# Get all headings
headings = wikicode.filter_headings()
if headings:
print(f"First heading: {headings[0].title}")
Debug
Known issues
breakingFrequent dropping of support for end-of-life Python versions. For example, v0.7.0 dropped Python 3.8, v0.6.6 dropped 3.7, and v0.6.5 dropped 3.6. Ensure your Python environment is kept up-to-date with supported versions (currently Python 3.9+).fixUpgrade your Python interpreter to a version officially supported by mwparserfromhell (currently Python 3.9+). Refer to the changelog for specific version requirements.
affects: 0.6.0 onwards
breakingIn v0.6.0, `Wikicode.matches()` was updated to recognize underscores as equivalent to spaces, and `Template.get()` gained a `default` parameter. Also, `Wikicode`'s `filter()` methods changed their default `recursive` parameter from `False` to `True`.fixReview usage of `Wikicode.matches()`, `Template.get()`, and `filter()` methods. Explicitly set `recursive=False` if non-recursive filtering is desired.
affects: 0.6.0
gotchaWhen installing from source, mwparserfromhell attempts to build a fast C tokenizer extension. If this fails (e.g., due to missing C compilers), it falls back to a slower pure-Python implementation. You can explicitly control this by setting the environment variable `WITH_EXTENSION=0` during installation to force the pure-Python version.fixIf experiencing installation issues related to C extensions, try `WITH_EXTENSION=0 pip install mwparserfromhell` or ensure a C compiler is available on your system.
affects: All versions
gotchamwparserfromhell operates on the raw wikicode. It cannot detect syntax elements produced by template transclusion (i.e., it doesn't expand templates) or resolve complex, cross-over syntax (e.g., `{{echo|''Hello}}, world!''`). For such cases, the parser may treat portions as plain text. The `skip_style_tags=True` parameter in `parse()` can sometimes help with formatting-related issues.fixBe aware of these limitations when parsing complex or transcluded wikicode. For rendered content, consider using MediaWiki's API or a different tool. For formatting issues, try `mwparserfromhell.parse(text, skip_style_tags=True)`.
affects: All versions
gotchaWhile `template['param_name']` (dict-style access) works for `Template` objects, it will raise a `ValueError` if the parameter does not exist. Using `template.get('param_name', default_value)` is generally safer and clearer for handling potentially missing parameters, similar to Python's dictionary `get` method.fixPrefer `template.get('param_name', default_value)` over `template['param_name']` when a parameter might be absent, to avoid unexpected `ValueError` exceptions. affects: All versions
gotchaThe nested node depth limit was raised from 40 to 100 in v0.6.6 to better match MediaWiki's parsing behavior. Extremely deeply nested wikicode structures might still hit this limit, potentially leading to incomplete parsing or errors.fixBe mindful of very deep nesting in wikicode. If encountering issues with deeply nested structures, consider simplifying the wikicode where possible or manually traversing the parsed tree to identify the problematic section.
affects: Pre-0.6.6 (limit 40), all versions (limit 100)
Upgrade
Version history
0.7.2latest on PyPI · released Jul 1, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.