IDE cannot resolve module import but works at runtime in PyCharm

Problem

When using PyCharm Pro 2025.3.3, importing a module like:

from authlib.integrations.requests_client import OAuth2Session

triggers editor errors such as Cannot find reference 'requests_client' in 'authlib.integrations' and Unresolved reference 'OAuth2Session'. These errors appear in the editor; however, the Python Packages tab correctly shows the package and dependencies, and the import works correctly in the Python Console.

Cause

The issue arises due to missing or incomplete type stubs for the authlib package. Without complete type hints, PyCharm cannot resolve some imports during static code analysis. This behavior does not impact runtime functionality, but it leads to editor warnings.

Resolution

To resolve the issue, install the relevant type stubs for the authlib package. Run the following command in your environment:

uv add types-authlib

This adds missing type information, allowing PyCharm to recognize and resolve the imports without warnings.

Additional Information

This is not a bug with PyCharm or the authlib package. The behavior is expected when a package lacks complete type hints. Installing type stubs resolves such issues for static analysis tools without impacting runtime behavior.

For other packages, similar typeshed stubs typically follow the naming convention types-<package_name> or <package_name>-stubs. If imports work at runtime but result in editor warnings, incomplete or missing typing support is the likely cause. Use these stub packages to address such scenarios.