Install & Compatibility
Where this runs
tested against v0.16.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.95 runs
installs and imports cleanly · install 0.0s · import 0.208s · 21MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.172s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nose2
✓ import nose2
Primarily used as a command-line tool, but can be imported for programmatic control or plugin development.
main
✓ import nose2.main
nose2.main()
Create a Python file (e.g., `test_math.py`) with test functions prefixed with `test_` or `unittest.TestCase` subclasses with `test_` methods. Then, simply navigate to your project directory in the terminal and run `nose2` to discover and execute tests.
import unittest
class MyTests(unittest.TestCase):
def test_addition(self):
self.assertEqual(1 + 1, 2)
def test_subtraction():
assert 5 - 2 == 3
# Save this as `test_math.py`
# To run from the command line: `nose2`
nose2 --version
Debug
Known issues
breakingnose2 is a distinct project from the original `nose` and is not fully backward compatible. `nose` plugins will not work with `nose2` without significant rewriting. Features like package-level fixtures supported by `nose` are not supported in `nose2`.fixReview `nose2`'s plugin API and `differences` documentation for migration guidance from `nose`.
affects: All versions (since inception)
breakingPython 2 is no longer supported; the last line supporting Python 2 was 0.12.x. As of version 0.16.0, support for Python 3.8 has also been removed. nose2 now requires Python >=3.9.fixEnsure your project runs on Python 3.9 or newer. Upgrade your Python environment if necessary.
affects: 0.13.0 and above (for Python 2), 0.16.0 and above (for Python 3.8)
deprecatedThe built-in `coverage` plugin is deprecated as of version 0.16.0 and is no longer tested on newer Python versions. It will be removed in a future release.fixConsider using alternative coverage tools or integrating `coverage.py` directly into your test workflow outside of `nose2`'s plugin system.
affects: 0.16.0 and above
gotcha`nose2` relies heavily on its plugin system; if no plugins are loaded (e.g., using `--no-plugins`), `nose2` effectively does nothing.fixEnsure that necessary plugins are enabled, either through configuration files (`unittest.cfg`, `nose2.cfg`, `pyproject.toml`) or command-line arguments.
affects: All versions
gotchaWhen using `test_suite='nose2.collector.collector'` with `python setup.py test`, `nose2` 'hijacks' the test running process, bypassing the standard `unittest` test result and runner. This might cause incompatibilities with certain packages or custom setups.fixPrefer running `nose2` directly from the command line (`nose2`) or use a dedicated test runner for your project if `setup.py test` causes issues.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nose2'
The 'nose2' package has not been installed in your Python environment or is not accessible.
fixRun `pip install nose2` to install the library.
No tests ran
Nose2 could not discover any test files or test cases, often due to naming conventions not matching the default `test_*.py` for files and `Test*` for classes, or incorrect directory structure.
fixEnsure test files are named `test_*.py` and test classes start with `Test`. Alternatively, specify a different test file pattern or starting directory in a `nose2.cfg` or `unittest.cfg` configuration file, for example: `[unittest] test-file-pattern=*.py`.
ImportError: No module named 'some_module_name'
This generic import error occurs when nose2 attempts to import a test module or a dependency, but Python cannot find the specified module, often due to missing `__init__.py` files in test directories or an incorrect Python path.
fixEnsure that all directories containing tests are valid Python packages (by including an `__init__.py` file) and that the project's root directory is on the Python path, or use the `--start-dir` and `--top-level-directory` options with `nose2`.
/bin/sh: 1: nose2: not found
The `nose2` executable script is not found in your system's PATH, meaning the operating system cannot locate the command when invoked directly.
fixInvoke nose2 using `python -m nose2` instead, or ensure that the directory containing the `nose2` script (usually in your Python environment's `bin` or `Scripts` folder) is added to your system's PATH.
Tests not running or unexpected behavior due to unittest.main()
A test file contains `unittest.main()` in its global scope, which causes the tests to be executed immediately when the module is imported by nose2, interfering with nose2's own test runner.
fixWrap `unittest.main()` calls within an `if __name__ == "__main__":` block in your test files to prevent it from executing when the module is imported by other test runners like nose2.
Upgrade
Version history
0.16.0latest on PyPI · released Mar 2, 2026
Audit
Dependencies
tomlioptionalRequired for loading TOML configuration (e.g., from `pyproject.toml`'s `tool.nose2` table) on Python versions older than 3.11.
coverageoptionalRequired for the coverage plugin functionality, though the built-in coverage plugin is deprecated.