Skip to content

pytest vs unittest: Which Should You Use?

pytest and unittest both run Python tests. unittest ships in the standard library and organizes tests as classes; pytest is a third-party package that lets tests be plain functions.

Start with pytest

Use pytest for almost every new project. It requires less code per test, reports failures in more detail, and its fixture system and plugins hold up as a suite grows. The Python ecosystem has largely settled on it: Django, Flask, FastAPI, pandas, NumPy, and SQLAlchemy all test with pytest or ship first-class pytest support.

unittest remains useful when a project cannot install third-party packages or depends on unittest-specific discovery and runner behavior. pytest collects ordinary unittest.TestCase subclasses and supports setUp and tearDown, so many existing suites can switch runners without rewriting tests. Check custom discovery hooks before switching.

Compare the frameworks

Compare assertions

unittest uses a class per group of tests and a named method for each check:

import unittest

class TestAdd(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(2, 3), 5)

pytest uses a plain function and Python’s built-in assert:

def test_add():
    assert add(2, 3) == 5

The payoff shows up on failure. pytest rewrites assert statements to report the operands, so a broken check explains itself:

$ pytest
>       assert add(2, 3) == 6
E       assert 5 == 6

unittest reports the same failure as AssertionError: 5 != 6. Both frameworks report useful differences for collections: unittest’s specialized methods such as assertDictEqual and assertListEqual also produce detailed diagnostics.

Compare setup and teardown

unittest shares setup through setUp and tearDown methods that run before and after every test in a class:

class TestApi(unittest.TestCase):
    def setUp(self):
        self.client = ApiClient()

    def tearDown(self):
        self.client.close()

pytest uses fixtures: functions a test requests by naming them as parameters. A fixture can be scoped to a function, class, module, or session, so expensive setup runs once and is shared:

import pytest

@pytest.fixture
def client():
    c = ApiClient()
    yield c
    c.close()

def test_call(client):
    assert client.get().status_code == 200

Fixtures compose (one fixture can request another) and live in a shared conftest.py without inheritance. That composability is the feature that teams miss most after moving away from setUp/tearDown.

Discover and select tests

Both frameworks auto-discover tests, but pytest’s selection is finer-grained. pytest collects files named test_*.py, functions named test_*, and classes named Test*, then lets you narrow a run by node id, substring, or marker:

pytest tests/test_api.py::test_login   # one test
pytest -k "login"                       # substring match
pytest -m slow                          # tests marked @pytest.mark.slow

unittest discovers TestCase subclasses and supports python -m unittest discover and python -m unittest -k login. Both runners have -k, with different matching rules; pytest also supports marker selection with -m.

Extend with plugins

pytest has a plugin ecosystem that unittest lacks. Parallel runs come from pytest-xdist, coverage from pytest-cov, and dozens more cover snapshots and property-based testing. See essential pytest plugins for the ones worth installing early. Parameterizing a test across inputs is built in:

@pytest.mark.parametrize("n,expected", [(2, 4), (3, 9)])
def test_square(n, expected):
    assert n * n == expected

unittest has subTest for repeated checks, but not pytest’s built-in parameterization and marker system.

Keep unittest when needed

Keep unittest as the runner when the environment cannot install third-party packages, or when tests rely on unittest-specific loading. In particular, pytest does not implement unittest’s load_tests protocol. A suite that builds test cases through load_tests needs a migration plan before switching runners.

Class-based tests are not a barrier to using pytest: it supports unittest.TestCase with setup and teardown methods. However, pytest’s fixture injection (apart from autouse fixtures), parametrization, and custom hooks do not work inside TestCase subclasses. unittest remains a maintained choice when those limitations matter.

Migrate existing unittest suites gradually

pytest collects conventionally named unittest.TestCase tests alongside plain-function tests. If the suite uses unittest’s custom load_tests protocol or specialized discovery, check those cases before switching:

$ pytest -q
..                                    [100%]
2 passed in 0.01s

For suites that use supported unittest features, pytest can be adopted as the runner while new tests are written as plain functions. python -m unittest does not discover pytest’s plain-function tests, so the two runners are not interchangeable.

To set up pytest from an empty project, follow Setting up testing with pytest and uv.

Last updated on