Install & Compatibility
Where this runs
tested against v4.0.0 · 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.925 runs
installs and imports cleanly · install 0.0s · import 0.164s · 29.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.1s · import 0.136s · 30MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
xmlrunner
✓ import xmlrunner
✗ from xmlrunner import XMLTestRunner
While `XMLTestRunner` is a class within the `xmlrunner` module, the typical usage is to import `xmlrunner` and then use `xmlrunner.XMLTestRunner` as the test runner in `unittest.main()`.
This example demonstrates how to set up a basic unittest suite and run it using `xmlrunner.XMLTestRunner` to generate XML reports in a specified directory. The `output` parameter in `XMLTestRunner` is used to define the directory for the reports.
import random
import unittest
import xmlrunner
import os
class TestSequenceFunctions(unittest.TestCase):
def setUp(self):
self.seq = list(range(10))
@unittest.skip("demonstrating skipping")
def test_skipped(self):
self.fail("shouldn't happen")
def test_shuffle(self):
# make sure the shuffled sequence does not lose any elements
random.shuffle(self.seq)
self.seq.sort()
self.assertEqual(self.seq, list(range(10)))
def test_choice(self):
element = random.choice(self.seq)
self.assertTrue(element in self.seq)
def test_sample(self):
with self.assertRaises(ValueError):
random.sample(self.seq, 20)
for element in random.sample(self.seq, 5):
self.assertTrue(element in self.seq)
if __name__ == '__main__':
output_dir = os.environ.get('TEST_REPORTS_DIR', 'test-reports')
os.makedirs(output_dir, exist_ok=True)
unittest.main(testRunner=xmlrunner.XMLTestRunner(output=output_dir),
failfast=False, buffer=False, catchbreak=False, exit=False)
xmlrunner --version
Debug
Known issues
breakingThe original `xmlrunner` PyPI package (version 1.7.7, from `pycontribs/xmlrunner`) is largely unmaintained and has known compatibility issues with newer Python versions (e.g., Python 3.11+).fixMigrate to `unittest-xml-reporting` (version 4.x.x+), which provides the `xmlrunner` module and is actively maintained. Install with `pip install unittest-xml-reporting`.
affects: xmlrunner <= 1.7.7
gotchaThere is a naming conflict where both an old, unmaintained `xmlrunner` package and the actively developed `unittest-xml-reporting` package exist. The latter is the recommended one and provides the `xmlrunner` module. Installing the incorrect package can lead to `ModuleNotFoundError` or outdated functionality.fixAlways install `unittest-xml-reporting` using `pip install unittest-xml-reporting`. The module to import will still be `import xmlrunner`.
affects: All versions
gotchaCustomization options like `TEST_OUTPUT_VERBOSE` and `TEST_OUTPUT_DESCRIPTIONS` primarily affect the console (stdout/stderr) output of the test runner, not the content of the generated XML reports.fixIf specific data needs to be in the XML report, it must be explicitly handled within the test case or by extending `XMLTestRunner`.
affects: All versions of unittest-xml-reporting
gotchaLogging output from test cases might not appear in the generated XML report by default. This often happens if `sys.stdout` or `sys.stderr` are overwritten within the test setup without proper handling by the runner.fixEnsure logging handlers are configured to output to a stream accessible by the `XMLTestRunner` or modify test cases to not interfere with `sys.stdout`/`sys.stderr`. One suggested fix is to set up the log handler inside the `setUp` function of your test case.
affects: All versions of unittest-xml-reporting
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'xmlrunner'
This typically occurs when you tried to install `xmlrunner` (the old package) instead of `unittest-xml-reporting`, or if `unittest-xml-reporting` was installed in an environment not on the Python path.
fixEnsure you install the correct package: `pip install unittest-xml-reporting`. Verify your Python environment and path if the issue persists.
ImportError: cannot import name '_TextTestResult' from 'unittest' (or 'ModuleNotFoundError: No module named 'unittest2'')
This error points to using the older `xmlrunner` package (version 1.7.7) with incompatible newer Python versions (e.g., Python 3.11 or later), which removed or changed internal `unittest` APIs that `xmlrunner` relied on.
fixUpgrade to the actively maintained `unittest-xml-reporting` by running `pip install --upgrade unittest-xml-reporting`. This version is compatible with modern Python releases.
Test reports are not generated or are empty when running tests with XMLRunner.
One common cause is that the test code itself or a dependency is overwriting `sys.stdout` or `sys.stderr` during the test execution, preventing `XMLTestRunner` from capturing the results.
fixReview your test code and any utilities that might manipulate `sys.stdout` or `sys.stderr`. Ensure these streams are not inadvertently closed or redirected in a way that blocks the test runner. Debugging the execution flow to see where the streams are altered can help.
Upgrade
Version history
4.0.0latest on PyPI · released Jan 7, 2026
Audit
Dependencies
No dependency data recorded yet.
Resources
No resource links recorded.