pytest vs unittest
pytest vs unittest compared for 2026: pytest 9.2 (plain assert with introspection, fixtures, parametrize, built-in subtests, 2,180 plugins, MIT) vs unittest in the Python 3.14/3.15 standard library (TestCase classes, zero dependencies, subTest, IsolatedAsyncioTestCase, colour output). Includes failure output, startup time and pytest-xdist results from runs we did, what pytest cannot do with TestCase classes, and a clear pick.
Quick Answer
unittest ships with Python, needs no install and starts almost instantly: in our run 2,000 trivial tests finished in about 0.15 s with python -m unittest, against about 1.3 s for pytest 9.2.0 on a warm cache. pytest is the de facto standard for new projects because tests are plain functions with plain assert statements, fixtures replace setUp/tearDown with reusable, scoped dependencies, @pytest.mark.parametrize turns one test into many with readable IDs, and 2,180 listed plugins add parallel runs (pytest-xdist), coverage, async and Django support. pytest also runs existing unittest suites unchanged, including subTest since pytest 9.0, so you can switch the runner first and convert tests later. Pick unittest when you cannot add dependencies (standard-library code, locked-down environments, tiny scripts) or must stay on the stdlib API; pick pytest for nearly every application or library where a dev dependency is acceptable.
Last updated November 21, 2026. Covers pytest 9.2.0 (27 October 2026) with pytest-xdist 3.8.0 and unittest in Python 3.14/3.15, with the pytest changelog, unittest-integration, plugin-list and compatibility pages and the Python unittest and devguide pages read on 21 November 2026, plus side-by-side runs we did that day.
| Feature | pytest | unittest |
|---|---|---|
| Licence & Distribution | MIT; installed from PyPI (pip install pytest); pytest-dev/pytest ~14.7k GitHub stars | Part of CPython (PSF licence); no install |
| Version Checked (Nov 2026) | 9.2.0 on 27 Oct 2026 (9.1.0 on 13 Jun 2026, 9.0.0 on 5 Nov 2025) | Ships with Python 3.15 (9 Oct 2026) and 3.14 (7 Oct 2025); bugfix branches |
| Python Versions | Python 3.10+ for pytest 9.x; official Python 3.15 support since 9.1.0 | Every supported CPython; features depend on version (e.g. 3.12 --durations, 3.14 colour, new asserts) |
| Test Style | Plain functions (classes optional, no base class) | Methods on unittest.TestCase subclasses |
| Assertions | Plain assert with rewriting and introspection; pytest.raises, pytest.warns, pytest.approx | assert* methods (assertEqual, assertIn, assertRaises, assertWarns, assertLogs; 3.14 adds assertStartsWith/assertEndsWith, assertIsSubclass and more) |
| Setup & Teardown | Fixtures with function/class/module/package/session scope, yield teardown, autouse, conftest.py sharing; xunit-style setup_* also supported | setUp/tearDown, setUpClass/tearDownClass, setUpModule/tearDownModule, addCleanup |
| Parametrised Tests | @pytest.mark.parametrize and parametrised fixtures; each case is a separate test item with its own ID | None built in; loops with subTest or third-party packages |
| Subtests | Built in since 9.0 (subtests fixture; reporting marked experimental); also runs unittest subTest | TestCase.subTest context manager (reported per failing case) |
| Test Discovery | test_*.py or *_test.py files, test_* functions, Test* classes; configurable | python -m unittest discover: test*.py by default, TestCase subclasses, load_tests protocol |
| Selecting Tests | -k expressions, -m markers, node IDs, --lf/--ff (last failed / failed first), -x and --maxfail | Module, class or method names; -k substring/pattern (3.7+); -f fail fast |
| Async Tests | Via plugins such as pytest-asyncio (1.5.0, Apache-2.0) or anyio's plugin; not in core | IsolatedAsyncioTestCase with asyncSetUp/asyncTearDown; loop_factory in 3.13 |
| Mocking | monkeypatch fixture built in; unittest.mock works unchanged; pytest-mock plugin optional | unittest.mock in the standard library (Mock, MagicMock, patch, AsyncMock) |
| Parallel Runs | pytest-xdist (-n auto starts one worker per CPU); not in core | None built in |
| Plugins & Extensions | 2,180 active plugins in the official list; hooks for writing your own | None; extend through TestResult/TestRunner subclasses or load_tests |
| Configuration | pyproject.toml [tool.pytest] (native TOML since 9.0), pytest.toml, pytest.ini, tox.ini, setup.cfg; strict mode | Command-line options and code; no configuration file |
| Reports for CI | --junitxml built in; durations, -ra summaries; HTML and coverage via plugins | Text runner; --durations (3.12+), --locals, -b buffer; no JUnit XML without a third-party runner |
| Exit Codes | 0 ok, 1 failures, 3 internal error, 4 usage error (incl. missing plugins since 9.2), 5 no tests collected (we saw 1 and 5) | 0 ok, 1 failures; 5 when no tests ran (we saw both) |
| Runs the Other's Tests | Yes: collects unittest.TestCase classes (setUp, setUpClass, setUpModule, skip, subTest); load_tests protocol not supported | No: cannot run pytest-style functions, fixtures or parametrize |
| Our Run: 2,000 trivial tests | 1.30 s wall on a warm cache (2.88 s first run), ~43 MB; same tests in TestCase style 1.57-1.71 s | 0.13-0.18 s wall, ~19-21 MB (Ran 2000 tests in ~0.06 s) |
| Our Run: 200 tests x 20 ms | Serial 4.59 s; -n 2 2.70 s; -n 4 1.90 s with pytest-xdist 3.8.0 | Not available; same work as one subTest loop 4.11 s |
pytest
pytest is the most widely used third-party test framework for Python. Tests are ordinary functions that use the plain assert statement; pytest rewrites assertions at import time so a failure shows the values involved and a diff. Dependencies are declared as fixtures, which pytest injects by argument name and can scope per test, class, module, package or session. pytest 9.0 (5 November 2025) merged subtests into the core, added native TOML configuration under [tool.pytest] and a strict mode, and dropped Python 3.9. pytest 9.2.0 shipped on 27 October 2026, is MIT-licensed and requires Python 3.10 or newer.
Pros
- Plain assert with introspection: failures show operand values and structured diffs for dicts, sets and long strings without any assert* method
- Fixtures with scopes, yield-based teardown and conftest.py sharing replace deep setUp hierarchies
- @pytest.mark.parametrize generates one reported test per case with IDs such as test_cases[100-1.0], and each case can be rerun on its own
- Large plugin ecosystem: the official list counts 2,180 active plugins, including pytest-xdist, pytest-cov, pytest-asyncio and pytest-django
- Runs existing unittest.TestCase suites unchanged, including subTest since 9.0, so migration can be gradual
- Rich selection and debugging: -k expressions, markers with -m, -x/--maxfail, --lf/--ff via the cache, --pdb
Cons
- A third-party dependency: not available in environments where only the standard library is allowed
- Slower start-up than unittest: about 1.3 s versus 0.15 s for 2,000 trivial tests in our run, mostly collection and assertion rewriting
- Fixture injection by argument name is implicit: a fixture can come from any conftest.py up the tree, which new readers find hard to trace
- Fixtures (except autouse), parametrize and custom hooks do not work inside unittest.TestCase classes, so mixed suites get the worst of both
- Breaking changes arrive with majors and some minors (9.2 made parametrize's indirect, ids and scope keyword-only), so pin the version in CI
Best For
New Python applications and libraries, projects that want fixtures and parametrisation, teams that need parallel runs, coverage or framework plugins, and existing unittest suites that want a better runner without rewriting.
unittest
unittest is the test framework in Python's standard library, modelled on JUnit's xUnit design. Tests are methods on unittest.TestCase subclasses, checks use assert* methods such as assertEqual and assertRaises, and setUp/tearDown plus class- and module-level hooks manage fixtures. It needs no installation, so it is always available wherever Python is. Recent releases keep adding small features: --durations in 3.12, a loop_factory for IsolatedAsyncioTestCase in 3.13, coloured output by default and new assertions such as assertStartsWith in 3.14. Its version is the Python version: 3.15 was released on 9 October 2026 and 3.14 on 7 October 2025.
Pros
- Zero dependencies: ships with every Python installation, so it works in locked-down, offline or standard-library-only projects
- Very fast start-up: 2,000 trivial tests ran in about 0.15 s wall time in our run, roughly 9x quicker than pytest
- Stable, documented API that changes only with Python releases and keeps old tests working for years
- Built-in async support with IsolatedAsyncioTestCase and the full unittest.mock library in the same module family
- Familiar xUnit structure for developers coming from JUnit, NUnit or similar frameworks
Cons
- Verbose: every test needs a TestCase subclass and assert* methods instead of plain assert
- No parametrisation: the closest tool is a subTest loop, which runs as a single test item that cannot be selected per case or split across workers
- No fixture injection or scoping beyond setUp/setUpClass/setUpModule, so shared resources lead to inheritance chains
- No plugin system, no built-in parallelism and no JUnit XML output; CI integration needs extra packages or a different runner
Best For
Standard-library-only code, environments where installing packages is not allowed, small scripts and teaching, and teams that need the test API to stay fixed for as long as Python does.
Two philosophies: xUnit classes versus plain functions
unittest follows the xUnit design that JUnit made popular. You subclass unittest.TestCase, write methods whose names start with test, prepare state in setUp and clean it in tearDown, and check results with assert* methods: assertEqual, assertIn, assertRaises, assertWarns, assertLogs and, from Python 3.14, assertStartsWith, assertEndsWith and assertIsSubclass. Shared state above one test goes into setUpClass or setUpModule. This is explicit and predictable, and it is why unittest code from ten years ago still runs. pytest starts from the opposite end. A test is any function named test_* in a test_*.py file, and you check results with the plain assert statement. pytest rewrites those statements when it imports the test module, so a failure prints the values on both sides and, for containers, a diff. Shared state is a fixture: a function decorated with @pytest.fixture that a test requests by naming it as an argument. Fixtures can depend on other fixtures, live in conftest.py files that apply to a whole directory, clean up after a yield, and be scoped per test, class, module, package or session. The result is less code per test, but more indirection: to find where a fixture comes from you may have to search several conftest.py files.
What we ran: the same failures, start-up time and parallel runs
On 21 November 2026 we ran pytest 9.2.0 with pytest-xdist 3.8.0 and the unittest module of Python 3.13.18 on a shared 2-vCPU sandbox. First, the same two failing checks in both styles: a dict whose currency was EUR instead of USD, and a discount case where 100% gave 0.0 instead of the expected 1.0. Both frameworks printed a usable dict diff. pytest additionally showed the fixture value and the parameters (pct = 100, expected = 1.0) and named the case test_cases[100-1.0], which can be rerun alone; unittest reported the subTest as (pct=100) inside a single test_cases method. Running the unittest file under pytest worked unchanged and reported SUBFAILED(pct=100) with the summary 2 failed, 1 passed, 3 subtests passed. Both exited 1 on failures and 5 when no tests were found. Second, 2,000 trivial tests split over 20 modules: python -m unittest discover took 0.13-0.18 s wall and about 20 MB; pytest took 1.30 s on a warm cache and 2.88 s on the first run while it wrote its assertion-rewrite cache, using about 43 MB. Third, parallelism: 200 tests that each sleep 20 ms took 4.59 s serially, 2.70 s with -n 2 and 1.90 s with -n 4. For the 2,000 trivial tests, -n 2 was slower than serial (2.22 s), because starting workers cost more than the tests. These are single short runs, not a benchmark.
Parametrisation and subtests: where the models differ most
Running the same test with many inputs is the most common reason teams leave unittest. unittest's tool is subTest: you loop over cases inside one test method and wrap each iteration in with self.subTest(...). A failing case is reported with its parameters and the loop continues. But the loop is still one test item. You cannot select a single case with -k or a node ID, rerun only the failed case, or give cases to different workers. In our run a 200-case subTest loop took 4.11 s with unittest and 4.74 s under pytest -n 2, because pytest-xdist had only one item to schedule, while the same cases written with @pytest.mark.parametrize dropped from 4.59 s to 2.70 s on two workers. pytest's parametrize creates a separate test per case, with IDs built from the values or from ids=, and it can be stacked to build a matrix or applied to fixtures so that every test using a fixture runs once per backend. Since pytest 9.0 there is also a built-in subtests fixture for cases only known at run time (for example one check per file found on disk), and pytest runs unittest's subTest the same way. The pytest changelog calls subtest reporting experimental, so the way failures are shown may still change. pytest 9.2 also made parametrize's indirect, ids and scope arguments keyword-only, which turns a classic mistake into a clear TypeError.
Migrating an existing unittest suite to pytest
You rarely need a big-bang rewrite. pytest collects unittest.TestCase subclasses in test_*.py and *_test.py files and supports almost all of their features: skip and skipIf decorators, setUp and tearDown, setUpClass and tearDownClass, setUpModule and tearDownModule, and subTest since version 9.0. The documented gap is the load_tests protocol, so suites that build their test list in code need a look before switching. Step one is therefore to install pytest, point CI at it and keep the tests as they are. You immediately get better tracebacks, output capturing, -k and -m selection, stop after the first N failures, --pdb, --lf to rerun only last failures, and parallel runs with pytest-xdist. Step two is converting files as you touch them: replace self.assertEqual(a, b) with assert a == b (the pytest docs point to the unittest2pytest tool for this), turn setUp into fixtures and loops into parametrize. Do not try to use fixtures, parametrize or custom hooks inside a TestCase class: the pytest docs say these do not work there and probably never will, apart from autouse fixtures and marks such as skip, skipif and xfail. The usual end state is plain functions in new code and a shrinking set of legacy TestCase files that keep running. The opposite move, from pytest back to unittest, means rewriting fixtures and parametrisation by hand.
Ecosystem, CI, versions and when unittest is still the right call
pytest's real lead is its ecosystem. The plugin list on docs.pytest.org counts 2,180 active plugins. The ones most projects add are pytest-xdist for parallel runs (-n auto starts one worker per CPU), pytest-cov for coverage, pytest-asyncio or anyio's plugin for async code and pytest-django or similar framework plugins. JUnit XML for CI dashboards is built in with --junitxml. unittest has no plugin system, no parallel runner and no JUnit XML writer; you extend it by subclassing TestRunner or TestResult, or by running the suite under pytest. Versioning is different too. unittest changes only with Python itself, so its API is effectively frozen for the life of a Python version. pytest moves faster: 9.0 dropped Python 3.9, 9.2 changed parametrize's signature and scheduled yield_fixture for removal in pytest 10 or 11, and pytest 9.x requires Python 3.10, which reached end of life on 1 October 2026. Pin pytest in CI and read the changelog before upgrading. 9.2 also keys the assertion-rewrite cache on a hash of the source instead of file timestamps, so a restored CI cache is no longer thrown away after each checkout. unittest remains the right tool for standard-library-only packages, CPython and other projects that cannot take dependencies, and short scripts where a near-instant run matters more than features. For everything else, see also our mypy vs Pyright, Ruff vs Black vs Flake8 and Vitest vs Jest comparisons.
Verdict
Pick pytest for any application or library where a development dependency is acceptable, which is almost all of them. Plain assert with real diffs, fixtures that scale from one test to a session-wide database, parametrize with per-case IDs and plugins for parallel runs, coverage, async code and Django add up to less test code and faster debugging, and the start-up cost (about a second for 2,000 tests in our run) disappears once tests do real work. If you already have a unittest suite, switch the runner to pytest first: it runs TestCase classes, setUpClass, setUpModule and subTest unchanged, so you gain better output, -k and --lf selection and pytest-xdist immediately, then convert files to plain functions as you touch them. Pick unittest when you cannot install anything (standard-library code, CPython itself, restricted or offline environments), for small scripts where a 0.1 s run matters, or when the test API must stay fixed for as long as the Python version does. Avoid half-migrated files that mix TestCase classes with pytest fixtures and parametrize: those features do not work inside TestCase.