pytest importmode default remains prepend while importlib is recommended

There is currently no official target release date for changing the default importmode from prepend to importlib. Because prepend modifies sys.path directly, switching the default would be a breaking change for legacy test suites that rely on implicit path resolution rather than proper package installation.

The Technical Distinction

The friction experienced by new projects stems from how pytest locates your code:

• Prepend (Default): Adds the project root to the front of sys.path. This is convenient for simple layouts but can cause "shadowing," where a local folder accidentally overrides an installed library of the same name.
• Importlib (Recommended): Uses Python's importlib machinery to load modules. This is the modern standard, especially for src/ layouts and namespace packages, as it avoids polluting the global path.

Implementation Steps for Modern Layouts

If you are using a src/ layout or namespace packages, you should explicitly opt into importlib now rather than waiting for a default change. Use one of the following methods:

Option 1: Configuration File (Permanent)

Add the setting to your pytest.ini or pyproject.toml to ensure consistency across all developer environments and CI/CD pipelines.

# pytest.ini
[pytest]
import_mode = importlib

Or for pyproject.toml:

# pyproject.toml
[tool.pytest.ini_options]
import_mode = "importlib"

Option 2: Command Line (Verification)

To verify if importlib resolves your imports correctly without changing your config, run:

pytest --import-mode=importlib

Migration and Compatibility

While a formal "compatibility shim" has not been announced, the current guidance for projects that cannot migrate immediately is to explicitly define import_mode = prepend in their configuration. This locks the behavior and prevents the suite from breaking when the pytest core team eventually updates the default.

Diagnostic Note: To provide more specific migration advice, it is necessary to know if your project uses a src/ layout or a flat layout (where the package resides in the root directory).