diff --git a/docs/advanced/embedding.rst b/docs/advanced/embedding.rst
index 98a5c52..dfdaad2 100644
--- a/docs/advanced/embedding.rst
+++ b/docs/advanced/embedding.rst
@@ -108,11 +108,11 @@
 Importing modules
 =================
 
-Python modules can be imported using `module::import()`:
+Python modules can be imported using `module_::import()`:
 
 .. code-block:: cpp
 
-    py::module sys = py::module::import("sys");
+    py::module_ sys = py::module_::import("sys");
     py::print(sys.attr("path"));
 
 For convenience, the current working directory is included in ``sys.path`` when
@@ -128,12 +128,12 @@
 
 .. code-block:: cpp
 
-    py::module calc = py::module::import("calc");
+    py::module_ calc = py::module_::import("calc");
     py::object result = calc.attr("add")(1, 2);
     int n = result.cast<int>();
     assert(n == 3);
 
-Modules can be reloaded using `module::reload()` if the source is modified e.g.
+Modules can be reloaded using `module_::reload()` if the source is modified e.g.
 by an external process. This can be useful in scenarios where the application
 imports a user defined data processing script which needs to be updated after
 changes by the user. Note that this function does not reload modules recursively.
@@ -153,7 +153,7 @@
     namespace py = pybind11;
 
     PYBIND11_EMBEDDED_MODULE(fast_calc, m) {
-        // `m` is a `py::module` which is used to bind functions and classes
+        // `m` is a `py::module_` which is used to bind functions and classes
         m.def("add", [](int i, int j) {
             return i + j;
         });
@@ -162,7 +162,7 @@
     int main() {
         py::scoped_interpreter guard{};
 
-        auto fast_calc = py::module::import("fast_calc");
+        auto fast_calc = py::module_::import("fast_calc");
         auto result = fast_calc.attr("add")(1, 2).cast<int>();
         assert(result == 3);
     }
@@ -196,7 +196,7 @@
     int main() {
         py::scoped_interpreter guard{};
 
-        auto py_module = py::module::import("py_module");
+        auto py_module = py::module_::import("py_module");
 
         auto locals = py::dict("fmt"_a="{} + {} = {}", **py_module.attr("__dict__"));
         assert(locals["a"].cast<int>() == 1);
diff --git a/docs/advanced/exceptions.rst b/docs/advanced/exceptions.rst
index a96f8e8..5eae556 100644
--- a/docs/advanced/exceptions.rst
+++ b/docs/advanced/exceptions.rst
@@ -182,7 +182,7 @@
 
     try {
         // open("missing.txt", "r")
-        auto file = py::module::import("io").attr("open")("missing.txt", "r");
+        auto file = py::module_::import("io").attr("open")("missing.txt", "r");
         auto text = file.attr("read")();
         file.attr("close")();
     } catch (py::error_already_set &e) {
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index c895517..81b4c02 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -17,7 +17,7 @@
 type information, it is not clear whether Python should take charge of the
 returned value and eventually free its resources, or if this is handled on the
 C++ side. For this reason, pybind11 provides a several *return value policy*
-annotations that can be passed to the :func:`module::def` and
+annotations that can be passed to the :func:`module_::def` and
 :func:`class_::def` functions. The default policy is
 :enum:`return_value_policy::automatic`.
 
diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst
index a5899c6..5aeb653 100644
--- a/docs/advanced/misc.rst
+++ b/docs/advanced/misc.rst
@@ -132,7 +132,7 @@
 
 .. code-block:: cpp
 
-    py::object pet = (py::object) py::module::import("basic").attr("Pet");
+    py::object pet = (py::object) py::module_::import("basic").attr("Pet");
 
     py::class_<Dog>(m, "Dog", pet)
         .def(py::init<const std::string &>())
@@ -146,7 +146,7 @@
 
 .. code-block:: cpp
 
-    py::module::import("basic");
+    py::module_::import("basic");
 
     py::class_<Dog, Pet>(m, "Dog")
         .def(py::init<const std::string &>())
@@ -243,7 +243,7 @@
 
     .. code-block:: cpp
 
-        auto atexit = py::module::import("atexit");
+        auto atexit = py::module_::import("atexit");
         atexit.attr("register")(py::cpp_function([]() {
             // perform cleanup here -- this function is called with the GIL held
         }));
@@ -284,7 +284,7 @@
     )mydelimiter");
 
 By default, pybind11 automatically generates and prepends a signature to the docstring of a function
-registered with ``module::def()`` and ``class_::def()``. Sometimes this
+registered with ``module_::def()`` and ``class_::def()``. Sometimes this
 behavior is not desirable, because you want to provide your own signature or remove
 the docstring completely to exclude the function from the Sphinx documentation.
 The class ``options`` allows you to selectively suppress auto-generated signatures:
diff --git a/docs/advanced/pycpp/object.rst b/docs/advanced/pycpp/object.rst
index 70e493a..6c7525c 100644
--- a/docs/advanced/pycpp/object.rst
+++ b/docs/advanced/pycpp/object.rst
@@ -56,12 +56,12 @@
 .. code-block:: cpp
 
     // Equivalent to "from decimal import Decimal"
-    py::object Decimal = py::module::import("decimal").attr("Decimal");
+    py::object Decimal = py::module_::import("decimal").attr("Decimal");
 
 .. code-block:: cpp
 
     // Try to import scipy
-    py::object scipy = py::module::import("scipy");
+    py::object scipy = py::module_::import("scipy");
     return scipy.attr("__version__");
 
 
@@ -81,7 +81,7 @@
 .. code-block:: cpp
 
     // Use Python to make our directories
-    py::object os = py::module::import("os");
+    py::object os = py::module_::import("os");
     py::object makedirs = os.attr("makedirs");
     makedirs("/tmp/path/to/somewhere");
 
@@ -196,9 +196,9 @@
     #include <pybind11/numpy.h>
     using namespace pybind11::literals;
 
-    py::module os = py::module::import("os");
-    py::module path = py::module::import("os.path");  // like 'import os.path as path'
-    py::module np = py::module::import("numpy");  // like 'import numpy as np'
+    py::module_ os = py::module_::import("os");
+    py::module_ path = py::module_::import("os.path");  // like 'import os.path as path'
+    py::module_ np = py::module_::import("numpy");  // like 'import numpy as np'
 
     py::str curdir_abs = path.attr("abspath")(path.attr("curdir"));
     py::print(py::str("Current directory: ") + curdir_abs);
diff --git a/docs/advanced/pycpp/utilities.rst b/docs/advanced/pycpp/utilities.rst
index 369e7c9..c15051f 100644
--- a/docs/advanced/pycpp/utilities.rst
+++ b/docs/advanced/pycpp/utilities.rst
@@ -42,7 +42,7 @@
     m.def("noisy_func", []() {
         py::scoped_ostream_redirect stream(
             std::cout,                               // std::ostream&
-            py::module::import("sys").attr("stdout") // Python output
+            py::module_::import("sys").attr("stdout") // Python output
         );
         call_noisy_func();
     });
@@ -104,7 +104,7 @@
     ...
 
     // Evaluate in scope of main module
-    py::object scope = py::module::import("__main__").attr("__dict__");
+    py::object scope = py::module_::import("__main__").attr("__dict__");
 
     // Evaluate an isolated expression
     int result = py::eval("my_variable + 10", scope).cast<int>();
diff --git a/docs/basics.rst b/docs/basics.rst
index 71440c9..0681d86 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -118,8 +118,8 @@
 The :func:`PYBIND11_MODULE` macro creates a function that will be called when an
 ``import`` statement is issued from within Python. The module name (``example``)
 is given as the first macro argument (it should not be in quotes). The second
-argument (``m``) defines a variable of type :class:`py::module <module>` which
-is the main interface for creating bindings. The method :func:`module::def`
+argument (``m``) defines a variable of type :class:`py::module_ <module>` which
+is the main interface for creating bindings. The method :func:`module_::def`
 generates binding code that exposes the ``add()`` function to Python.
 
 .. note::
@@ -181,7 +181,7 @@
           py::arg("i"), py::arg("j"));
 
 :class:`arg` is one of several special tag classes which can be used to pass
-metadata into :func:`module::def`. With this modified binding code, we can now
+metadata into :func:`module_::def`. With this modified binding code, we can now
 call the function using keyword arguments, which is a more readable alternative
 particularly for functions taking many parameters:
 
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 1b022b9..568611b 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -11,9 +11,9 @@
 
 See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
 
-* Provide an additional spelling of ``py::module`` - ``py::module_`` (with a
-  trailing underscore), for C++20 compatibility. Only relevant when used
-  unqualified.
+* ``py::module`` was renamed ``py::module_`` to avoid issues with C++20 when
+  used unqualified, but an alias ``py::module`` is provided for backward
+  compatibility.
   `#2489 <https://github.com/pybind/pybind11/pull/2489>`_
 
 * ``pybind11_add_module()`` now accepts an optional ``OPT_SIZE`` flag that
@@ -529,7 +529,7 @@
 v2.2.1 (September 14, 2017)
 -----------------------------------------------------
 
-* Added ``py::module::reload()`` member function for reloading a module.
+* Added ``py::module_::reload()`` member function for reloading a module.
   `#1040 <https://github.com/pybind/pybind11/pull/1040>`_.
 
 * Fixed a reference leak in the number converter.
diff --git a/docs/faq.rst b/docs/faq.rst
index 5f7866f..daf7c08 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -100,8 +100,8 @@
 
 .. code-block:: cpp
 
-    void init_ex1(py::module &);
-    void init_ex2(py::module &);
+    void init_ex1(py::module_ &);
+    void init_ex2(py::module_ &);
     /* ... */
 
     PYBIND11_MODULE(example, m) {
@@ -114,7 +114,7 @@
 
 .. code-block:: cpp
 
-    void init_ex1(py::module &m) {
+    void init_ex1(py::module_ &m) {
         m.def("add", [](int a, int b) { return a + b; });
     }
 
@@ -122,7 +122,7 @@
 
 .. code-block:: cpp
 
-    void init_ex2(py::module &m) {
+    void init_ex2(py::module_ &m) {
         m.def("sub", [](int a, int b) { return a - b; });
     }
 
diff --git a/include/pybind11/detail/class.h b/include/pybind11/detail/class.h
index ecc6fb5..8c3c3a0 100644
--- a/include/pybind11/detail/class.h
+++ b/include/pybind11/detail/class.h
@@ -569,17 +569,17 @@
 #endif
     }
 
-    object module;
+    object module_;
     if (rec.scope) {
         if (hasattr(rec.scope, "__module__"))
-            module = rec.scope.attr("__module__");
+            module_ = rec.scope.attr("__module__");
         else if (hasattr(rec.scope, "__name__"))
-            module = rec.scope.attr("__name__");
+            module_ = rec.scope.attr("__name__");
     }
 
     auto full_name = c_str(
 #if !defined(PYPY_VERSION)
-        module ? str(module).cast<std::string>() + "." + rec.name :
+        module_ ? str(module_).cast<std::string>() + "." + rec.name :
 #endif
         rec.name);
 
@@ -658,8 +658,8 @@
     else
         Py_INCREF(type); // Keep it alive forever (reference leak)
 
-    if (module) // Needed by pydoc
-        setattr((PyObject *) type, "__module__", module);
+    if (module_) // Needed by pydoc
+        setattr((PyObject *) type, "__module__", module_);
 
     PYBIND11_SET_OLDPY_QUALNAME(type, qualname);
 
diff --git a/include/pybind11/detail/common.h b/include/pybind11/detail/common.h
index d14981f..7e06287 100644
--- a/include/pybind11/detail/common.h
+++ b/include/pybind11/detail/common.h
@@ -263,13 +263,13 @@
     ***Deprecated in favor of PYBIND11_MODULE***
 
     This macro creates the entry point that will be invoked when the Python interpreter
-    imports a plugin library. Please create a `module` in the function body and return
+    imports a plugin library. Please create a `module_` in the function body and return
     the pointer to its underlying Python object at the end.
 
     .. code-block:: cpp
 
         PYBIND11_PLUGIN(example) {
-            pybind11::module m("example", "pybind11 example plugin");
+            pybind11::module_ m("example", "pybind11 example plugin");
             /// Set up bindings here
             return m.ptr();
         }
@@ -290,7 +290,7 @@
     This macro creates the entry point that will be invoked when the Python interpreter
     imports an extension module. The module name is given as the fist argument and it
     should not be in quotes. The second macro argument defines a variable of type
-    `py::module` which can be used to initialize the module.
+    `py::module_` which can be used to initialize the module.
 
     The entry point is marked as "maybe unused" to aid dead-code detection analysis:
     since the entry point is typically only looked up at runtime and not referenced
@@ -317,12 +317,12 @@
 #else
 #define PYBIND11_DETAIL_MODULE_STATIC_DEF(name)
 #define PYBIND11_DETAIL_MODULE_CREATE(name)                                    \
-        auto m = pybind11::module(PYBIND11_TOSTRING(name));
+        auto m = pybind11::module_(PYBIND11_TOSTRING(name));
 #endif
 #define PYBIND11_MODULE(name, variable)                                        \
     PYBIND11_DETAIL_MODULE_STATIC_DEF(name)                                    \
     PYBIND11_MAYBE_UNUSED                                                      \
-    static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &);     \
+    static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module_ &);     \
     PYBIND11_PLUGIN_IMPL(name) {                                               \
         PYBIND11_CHECK_PYTHON_VERSION                                          \
         PYBIND11_ENSURE_INTERNALS_READY                                        \
@@ -332,7 +332,7 @@
             return m.ptr();                                                    \
         } PYBIND11_CATCH_INIT_EXCEPTIONS                                       \
     }                                                                          \
-    void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &variable)
+    void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module_ &variable)
 
 
 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
diff --git a/include/pybind11/eigen.h b/include/pybind11/eigen.h
index 12ce9bd..58582b2 100644
--- a/include/pybind11/eigen.h
+++ b/include/pybind11/eigen.h
@@ -549,7 +549,7 @@
             return false;
 
         auto obj = reinterpret_borrow<object>(src);
-        object sparse_module = module::import("scipy.sparse");
+        object sparse_module = module_::import("scipy.sparse");
         object matrix_type = sparse_module.attr(
             rowMajor ? "csr_matrix" : "csc_matrix");
 
@@ -580,7 +580,7 @@
     static handle cast(const Type &src, return_value_policy /* policy */, handle /* parent */) {
         const_cast<Type&>(src).makeCompressed();
 
-        object matrix_type = module::import("scipy.sparse").attr(
+        object matrix_type = module_::import("scipy.sparse").attr(
             rowMajor ? "csr_matrix" : "csc_matrix");
 
         array data(src.nonZeros(), src.valuePtr());
diff --git a/include/pybind11/embed.h b/include/pybind11/embed.h
index eae86c7..2d94e17 100644
--- a/include/pybind11/embed.h
+++ b/include/pybind11/embed.h
@@ -46,9 +46,9 @@
         }
  \endrst */
 #define PYBIND11_EMBEDDED_MODULE(name, variable)                              \
-    static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &);    \
+    static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module_ &);    \
     static PyObject PYBIND11_CONCAT(*pybind11_init_wrapper_, name)() {        \
-        auto m = pybind11::module(PYBIND11_TOSTRING(name));                   \
+        auto m = pybind11::module_(PYBIND11_TOSTRING(name));                   \
         try {                                                                 \
             PYBIND11_CONCAT(pybind11_init_, name)(m);                         \
             return m.ptr();                                                   \
@@ -64,7 +64,7 @@
     pybind11::detail::embedded_module PYBIND11_CONCAT(pybind11_module_, name) \
                               (PYBIND11_TOSTRING(name),             \
                                PYBIND11_CONCAT(pybind11_init_impl_, name));   \
-    void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &variable)
+    void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module_ &variable)
 
 
 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
@@ -109,7 +109,7 @@
     Py_InitializeEx(init_signal_handlers ? 1 : 0);
 
     // Make .py files in the working directory available by default
-    module::import("sys").attr("path").cast<list>().append(".");
+    module_::import("sys").attr("path").cast<list>().append(".");
 }
 
 /** \rst
diff --git a/include/pybind11/eval.h b/include/pybind11/eval.h
index ba82cf4..4e44702 100644
--- a/include/pybind11/eval.h
+++ b/include/pybind11/eval.h
@@ -52,7 +52,7 @@
 template <eval_mode mode = eval_expr, size_t N>
 object eval(const char (&s)[N], object global = globals(), object local = object()) {
     /* Support raw string literals by removing common leading whitespace */
-    auto expr = (s[0] == '\n') ? str(module::import("textwrap").attr("dedent")(s))
+    auto expr = (s[0] == '\n') ? str(module_::import("textwrap").attr("dedent")(s))
                                : str(s);
     return eval<mode>(expr, global, local);
 }
diff --git a/include/pybind11/iostream.h b/include/pybind11/iostream.h
index 48479f2..5e9a814 100644
--- a/include/pybind11/iostream.h
+++ b/include/pybind11/iostream.h
@@ -102,7 +102,7 @@
     .. code-block:: cpp
 
         {
-            py::scoped_ostream_redirect output{std::cerr, py::module::import("sys").attr("stderr")};
+            py::scoped_ostream_redirect output{std::cerr, py::module_::import("sys").attr("stderr")};
             std::cerr << "Hello, World!";
         }
  \endrst */
@@ -115,7 +115,7 @@
 public:
     scoped_ostream_redirect(
             std::ostream &costream = std::cout,
-            object pyostream = module::import("sys").attr("stdout"))
+            object pyostream = module_::import("sys").attr("stdout"))
         : costream(costream), buffer(pyostream) {
         old = costream.rdbuf(&buffer);
     }
@@ -146,7 +146,7 @@
 public:
     scoped_estream_redirect(
             std::ostream &costream = std::cerr,
-            object pyostream = module::import("sys").attr("stderr"))
+            object pyostream = module_::import("sys").attr("stderr"))
         : scoped_ostream_redirect(costream,pyostream) {}
 };
 
@@ -206,7 +206,7 @@
             m.noisy_function_with_error_printing()
 
  \endrst */
-inline class_<detail::OstreamRedirect> add_ostream_redirect(module m, std::string name = "ostream_redirect") {
+inline class_<detail::OstreamRedirect> add_ostream_redirect(module_ m, std::string name = "ostream_redirect") {
     return class_<detail::OstreamRedirect>(m, name.c_str(), module_local())
         .def(init<bool,bool>(), arg("stdout")=true, arg("stderr")=true)
         .def("__enter__", &detail::OstreamRedirect::enter)
diff --git a/include/pybind11/numpy.h b/include/pybind11/numpy.h
index 54e160f..a43119e 100644
--- a/include/pybind11/numpy.h
+++ b/include/pybind11/numpy.h
@@ -222,7 +222,7 @@
     };
 
     static npy_api lookup() {
-        module_ m = module::import("numpy.core.multiarray");
+        module_ m = module_::import("numpy.core.multiarray");
         auto c = m.attr("_ARRAY_API");
 #if PY_MAJOR_VERSION >= 3
         void **api_ptr = (void **) PyCapsule_GetPointer(c.ptr(), NULL);
@@ -505,7 +505,7 @@
 
 private:
     static object _dtype_from_pep3118() {
-        static PyObject *obj = module::import("numpy.core._internal")
+        static PyObject *obj = module_::import("numpy.core._internal")
             .attr("_dtype_from_pep3118").cast<object>().release().ptr();
         return reinterpret_borrow<object>(obj);
     }
diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h
index 265a147..db0efd4 100644
--- a/include/pybind11/pybind11.h
+++ b/include/pybind11/pybind11.h
@@ -904,9 +904,9 @@
 
         .. code-block:: cpp
 
-            py::module m("example", "pybind11 example plugin");
-            py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
-            py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
+            py::module_ m("example", "pybind11 example plugin");
+            py::module_ m2 = m.def_submodule("sub", "A submodule of 'example'");
+            py::module_ m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
     \endrst */
     module_ def_submodule(const char *name, const char *doc = nullptr) {
         std::string full_name = std::string(PyModule_GetName(m_ptr))
@@ -965,12 +965,15 @@
         };
         m_ptr = PyModule_Create(def);
         if (m_ptr == nullptr)
-            pybind11_fail("Internal error in module::module()");
+            pybind11_fail("Internal error in module_::module_()");
         inc_ref();
     }
 #endif
 };
 
+// When inside a namespace (or anywhere as long as it's not the first item on a line),
+// C++20 allows "module" to be used. This is provided for backward compatibility, and for
+// simplicity, if someone wants to use py::module for example, that is perfectly safe.
 using module = module_;
 
 #if PY_MAJOR_VERSION >= 3
@@ -986,7 +989,7 @@
 /// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded).
 inline dict globals() {
     PyObject *p = PyEval_GetGlobals();
-    return reinterpret_borrow<dict>(p ? p : module::import("__main__").attr("__dict__").ptr());
+    return reinterpret_borrow<dict>(p ? p : module_::import("__main__").attr("__dict__").ptr());
 }
 
 PYBIND11_NAMESPACE_BEGIN(detail)
@@ -1973,7 +1976,7 @@
         file = kwargs["file"].cast<object>();
     } else {
         try {
-            file = module::import("sys").attr("stdout");
+            file = module_::import("sys").attr("stdout");
         } catch (const error_already_set &) {
             /* If print() is called from code that is executed as
                part of garbage collection during interpreter shutdown,
diff --git a/tests/constructor_stats.h b/tests/constructor_stats.h
index abfaf91..805968a 100644
--- a/tests/constructor_stats.h
+++ b/tests/constructor_stats.h
@@ -120,7 +120,7 @@
             throw py::error_already_set();
         Py_DECREF(result);
 #else
-        py::module::import("gc").attr("collect")();
+        py::module_::import("gc").attr("collect")();
 #endif
     }
 
diff --git a/tests/pybind11_tests.cpp b/tests/pybind11_tests.cpp
index 24b65df..439cd40 100644
--- a/tests/pybind11_tests.cpp
+++ b/tests/pybind11_tests.cpp
@@ -26,8 +26,8 @@
 Instead, see the "How can I reduce the build time?" question in the "Frequently asked questions"
 section of the documentation for good practice on splitting binding code over multiple files.
 */
-std::list<std::function<void(py::module &)>> &initializers() {
-    static std::list<std::function<void(py::module &)>> inits;
+std::list<std::function<void(py::module_ &)>> &initializers() {
+    static std::list<std::function<void(py::module_ &)>> inits;
     return inits;
 }
 
@@ -36,13 +36,13 @@
 }
 
 test_initializer::test_initializer(const char *submodule_name, Initializer init) {
-    initializers().emplace_back([=](py::module &parent) {
+    initializers().emplace_back([=](py::module_ &parent) {
         auto m = parent.def_submodule(submodule_name);
         init(m);
     });
 }
 
-void bind_ConstructorStats(py::module &m) {
+void bind_ConstructorStats(py::module_ &m) {
     py::class_<ConstructorStats>(m, "ConstructorStats")
         .def("alive", &ConstructorStats::alive)
         .def("values", &ConstructorStats::values)
diff --git a/tests/pybind11_tests.h b/tests/pybind11_tests.h
index 247f799..4ff56c0 100644
--- a/tests/pybind11_tests.h
+++ b/tests/pybind11_tests.h
@@ -10,7 +10,7 @@
 using namespace pybind11::literals;
 
 class test_initializer {
-    using Initializer = void (*)(py::module &);
+    using Initializer = void (*)(py::module_ &);
 
 public:
     test_initializer(Initializer init);
@@ -18,9 +18,9 @@
 };
 
 #define TEST_SUBMODULE(name, variable)                   \
-    void test_submodule_##name(py::module &);            \
+    void test_submodule_##name(py::module_ &);            \
     test_initializer name(#name, test_submodule_##name); \
-    void test_submodule_##name(py::module &variable)
+    void test_submodule_##name(py::module_ &variable)
 
 
 /// Dummy type which is not exported anywhere -- something to trigger a conversion error
diff --git a/tests/test_async.cpp b/tests/test_async.cpp
index f0ad0d5..e6e01d7 100644
--- a/tests/test_async.cpp
+++ b/tests/test_async.cpp
@@ -18,7 +18,7 @@
         .def(py::init<>())
         .def("__await__", [](const SupportsAsync& self) -> py::object {
             static_cast<void>(self);
-            py::object loop = py::module::import("asyncio.events").attr("get_event_loop")();
+            py::object loop = py::module_::import("asyncio.events").attr("get_event_loop")();
             py::object f = loop.attr("create_future")();
             f.attr("set_result")(5);
             return f.attr("__await__")();
diff --git a/tests/test_class.cpp b/tests/test_class.cpp
index 3ca9d2a..2d4aef7 100644
--- a/tests/test_class.cpp
+++ b/tests/test_class.cpp
@@ -172,12 +172,12 @@
     struct MismatchDerived2 : MismatchBase2 { };
 
     m.def("mismatched_holder_1", []() {
-        auto mod = py::module::import("__main__");
+        auto mod = py::module_::import("__main__");
         py::class_<MismatchBase1, std::shared_ptr<MismatchBase1>>(mod, "MismatchBase1");
         py::class_<MismatchDerived1, MismatchBase1>(mod, "MismatchDerived1");
     });
     m.def("mismatched_holder_2", []() {
-        auto mod = py::module::import("__main__");
+        auto mod = py::module_::import("__main__");
         py::class_<MismatchBase2>(mod, "MismatchBase2");
         py::class_<MismatchDerived2, std::shared_ptr<MismatchDerived2>,
                    MismatchBase2>(mod, "MismatchDerived2");
diff --git a/tests/test_cmake_build/embed.cpp b/tests/test_cmake_build/embed.cpp
index b9581d2..a3abc8a 100644
--- a/tests/test_cmake_build/embed.cpp
+++ b/tests/test_cmake_build/embed.cpp
@@ -12,10 +12,10 @@
 
     py::scoped_interpreter guard{};
 
-    auto m = py::module::import("test_cmake_build");
+    auto m = py::module_::import("test_cmake_build");
     if (m.attr("add")(1, 2).cast<int>() != 3)
         throw std::runtime_error("embed.cpp failed");
 
-    py::module::import("sys").attr("argv") = py::make_tuple("test.py", "embed.cpp");
+    py::module_::import("sys").attr("argv") = py::make_tuple("test.py", "embed.cpp");
     py::eval_file(test_py_file, py::globals());
 }
diff --git a/tests/test_eigen.cpp b/tests/test_eigen.cpp
index 56aa1a4..807d0a3 100644
--- a/tests/test_eigen.cpp
+++ b/tests/test_eigen.cpp
@@ -317,11 +317,11 @@
     // a new array (np.ones(10)) increases the chances that the temp array will be garbage
     // collected and/or that its memory will be overridden with different values.
     m.def("get_elem_direct", [](Eigen::Ref<const Eigen::VectorXd> v) {
-        py::module::import("numpy").attr("ones")(10);
+        py::module_::import("numpy").attr("ones")(10);
         return v(5);
     });
     m.def("get_elem_indirect", [](std::vector<Eigen::Ref<const Eigen::VectorXd>> v) {
-        py::module::import("numpy").attr("ones")(10);
+        py::module_::import("numpy").attr("ones")(10);
         return v[0](5);
     });
 }
diff --git a/tests/test_embed/test_interpreter.cpp b/tests/test_embed/test_interpreter.cpp
index 753ce54..944334c 100644
--- a/tests/test_embed/test_interpreter.cpp
+++ b/tests/test_embed/test_interpreter.cpp
@@ -51,17 +51,17 @@
 }
 
 TEST_CASE("Pass classes and data between modules defined in C++ and Python") {
-    auto module = py::module::import("test_interpreter");
-    REQUIRE(py::hasattr(module, "DerivedWidget"));
+    auto module_ = py::module_::import("test_interpreter");
+    REQUIRE(py::hasattr(module_, "DerivedWidget"));
 
-    auto locals = py::dict("hello"_a="Hello, World!", "x"_a=5, **module.attr("__dict__"));
+    auto locals = py::dict("hello"_a="Hello, World!", "x"_a=5, **module_.attr("__dict__"));
     py::exec(R"(
         widget = DerivedWidget("{} - {}".format(hello, x))
         message = widget.the_message
     )", py::globals(), locals);
     REQUIRE(locals["message"].cast<std::string>() == "Hello, World! - 5");
 
-    auto py_widget = module.attr("DerivedWidget")("The question");
+    auto py_widget = module_.attr("DerivedWidget")("The question");
     auto message = py_widget.attr("the_message");
     REQUIRE(message.cast<std::string>() == "The question");
 
@@ -70,10 +70,10 @@
 }
 
 TEST_CASE("Import error handling") {
-    REQUIRE_NOTHROW(py::module::import("widget_module"));
-    REQUIRE_THROWS_WITH(py::module::import("throw_exception"),
+    REQUIRE_NOTHROW(py::module_::import("widget_module"));
+    REQUIRE_THROWS_WITH(py::module_::import("throw_exception"),
                         "ImportError: C++ Error");
-    REQUIRE_THROWS_WITH(py::module::import("throw_error_already_set"),
+    REQUIRE_THROWS_WITH(py::module_::import("throw_error_already_set"),
                         Catch::Contains("ImportError: KeyError"));
 }
 
@@ -107,14 +107,14 @@
 
 TEST_CASE("Restart the interpreter") {
     // Verify pre-restart state.
-    REQUIRE(py::module::import("widget_module").attr("add")(1, 2).cast<int>() == 3);
+    REQUIRE(py::module_::import("widget_module").attr("add")(1, 2).cast<int>() == 3);
     REQUIRE(has_pybind11_internals_builtin());
     REQUIRE(has_pybind11_internals_static());
-    REQUIRE(py::module::import("external_module").attr("A")(123).attr("value").cast<int>() == 123);
+    REQUIRE(py::module_::import("external_module").attr("A")(123).attr("value").cast<int>() == 123);
 
     // local and foreign module internals should point to the same internals:
     REQUIRE(reinterpret_cast<uintptr_t>(*py::detail::get_internals_pp()) ==
-            py::module::import("external_module").attr("internals_at")().cast<uintptr_t>());
+            py::module_::import("external_module").attr("internals_at")().cast<uintptr_t>());
 
     // Restart the interpreter.
     py::finalize_interpreter();
@@ -130,14 +130,14 @@
     REQUIRE(has_pybind11_internals_builtin());
     REQUIRE(has_pybind11_internals_static());
     REQUIRE(reinterpret_cast<uintptr_t>(*py::detail::get_internals_pp()) ==
-            py::module::import("external_module").attr("internals_at")().cast<uintptr_t>());
+            py::module_::import("external_module").attr("internals_at")().cast<uintptr_t>());
 
     // Make sure that an interpreter with no get_internals() created until finalize still gets the
     // internals destroyed
     py::finalize_interpreter();
     py::initialize_interpreter();
     bool ran = false;
-    py::module::import("__main__").attr("internals_destroy_test") =
+    py::module_::import("__main__").attr("internals_destroy_test") =
         py::capsule(&ran, [](void *ran) { py::detail::get_internals(); *static_cast<bool *>(ran) = true; });
     REQUIRE_FALSE(has_pybind11_internals_builtin());
     REQUIRE_FALSE(has_pybind11_internals_static());
@@ -149,20 +149,20 @@
     REQUIRE_FALSE(has_pybind11_internals_static());
 
     // C++ modules can be reloaded.
-    auto cpp_module = py::module::import("widget_module");
+    auto cpp_module = py::module_::import("widget_module");
     REQUIRE(cpp_module.attr("add")(1, 2).cast<int>() == 3);
 
     // C++ type information is reloaded and can be used in python modules.
-    auto py_module = py::module::import("test_interpreter");
+    auto py_module = py::module_::import("test_interpreter");
     auto py_widget = py_module.attr("DerivedWidget")("Hello after restart");
     REQUIRE(py_widget.attr("the_message").cast<std::string>() == "Hello after restart");
 }
 
 TEST_CASE("Subinterpreter") {
     // Add tags to the modules in the main interpreter and test the basics.
-    py::module::import("__main__").attr("main_tag") = "main interpreter";
+    py::module_::import("__main__").attr("main_tag") = "main interpreter";
     {
-        auto m = py::module::import("widget_module");
+        auto m = py::module_::import("widget_module");
         m.attr("extension_module_tag") = "added to module in main interpreter";
 
         REQUIRE(m.attr("add")(1, 2).cast<int>() == 3);
@@ -181,9 +181,9 @@
     REQUIRE(has_pybind11_internals_static());
 
     // Modules tags should be gone.
-    REQUIRE_FALSE(py::hasattr(py::module::import("__main__"), "tag"));
+    REQUIRE_FALSE(py::hasattr(py::module_::import("__main__"), "tag"));
     {
-        auto m = py::module::import("widget_module");
+        auto m = py::module_::import("widget_module");
         REQUIRE_FALSE(py::hasattr(m, "extension_module_tag"));
 
         // Function bindings should still work.
@@ -194,8 +194,8 @@
     Py_EndInterpreter(sub_tstate);
     PyThreadState_Swap(main_tstate);
 
-    REQUIRE(py::hasattr(py::module::import("__main__"), "main_tag"));
-    REQUIRE(py::hasattr(py::module::import("widget_module"), "extension_module_tag"));
+    REQUIRE(py::hasattr(py::module_::import("__main__"), "main_tag"));
+    REQUIRE(py::hasattr(py::module_::import("widget_module"), "extension_module_tag"));
 }
 
 TEST_CASE("Execution frame") {
@@ -245,7 +245,7 @@
     // Disable generation of cached bytecode (.pyc files) for this test, otherwise
     // Python might pick up an old version from the cache instead of the new versions
     // of the .py files generated below
-    auto sys = py::module::import("sys");
+    auto sys = py::module_::import("sys");
     bool dont_write_bytecode = sys.attr("dont_write_bytecode").cast<bool>();
     sys.attr("dont_write_bytecode") = true;
     // Reset the value at scope exit
@@ -267,8 +267,8 @@
     });
 
     // Import the module from file
-    auto module = py::module::import(module_name.c_str());
-    int result = module.attr("test")().cast<int>();
+    auto module_ = py::module_::import(module_name.c_str());
+    int result = module_.attr("test")().cast<int>();
     REQUIRE(result == 1);
 
     // Update the module .py file with a small change
@@ -278,7 +278,7 @@
     test_module.close();
 
     // Reload the module
-    module.reload();
-    result = module.attr("test")().cast<int>();
+    module_.reload();
+    result = module_.attr("test")().cast<int>();
     REQUIRE(result == 2);
 }
diff --git a/tests/test_eval.cpp b/tests/test_eval.cpp
index e094821..03d0fb3 100644
--- a/tests/test_eval.cpp
+++ b/tests/test_eval.cpp
@@ -14,7 +14,7 @@
 TEST_SUBMODULE(eval_, m) {
     // test_evals
 
-    auto global = py::dict(py::module::import("__main__").attr("__dict__"));
+    auto global = py::dict(py::module_::import("__main__").attr("__dict__"));
 
     m.def("test_eval_statements", [global]() {
         auto local = py::dict();
diff --git a/tests/test_exceptions.cpp b/tests/test_exceptions.cpp
index 6187f2e..b95ff47 100644
--- a/tests/test_exceptions.cpp
+++ b/tests/test_exceptions.cpp
@@ -163,7 +163,7 @@
     m.def("modulenotfound_exception_matches_base", []() {
         try {
             // On Python >= 3.6, this raises a ModuleNotFoundError, a subclass of ImportError
-            py::module::import("nonexistent");
+            py::module_::import("nonexistent");
         }
         catch (py::error_already_set &ex) {
             if (!ex.matches(PyExc_ImportError)) throw;
diff --git a/tests/test_factory_constructors.cpp b/tests/test_factory_constructors.cpp
index 2368dab..f42d1f2 100644
--- a/tests/test_factory_constructors.cpp
+++ b/tests/test_factory_constructors.cpp
@@ -142,7 +142,7 @@
 TEST_SUBMODULE(factory_constructors, m) {
 
     // Define various trivial types to allow simpler overload resolution:
-    py::module m_tag = m.def_submodule("tag");
+    py::module_ m_tag = m.def_submodule("tag");
 #define MAKE_TAG_TYPE(Name) \
     struct Name##_tag {}; \
     py::class_<Name##_tag>(m_tag, #Name "_tag").def(py::init<>()); \
diff --git a/tests/test_gil_scoped.cpp b/tests/test_gil_scoped.cpp
index eb63089..b6a45a5 100644
--- a/tests/test_gil_scoped.cpp
+++ b/tests/test_gil_scoped.cpp
@@ -45,7 +45,7 @@
           [](VirtClass &virt) { virt.pure_virtual_func(); });
     m.def("test_cross_module_gil",
           []() {
-              auto cm = py::module::import("cross_module_gil_utils");
+              auto cm = py::module_::import("cross_module_gil_utils");
               auto gil_acquire = reinterpret_cast<void (*)()>(
                   PyLong_AsVoidPtr(cm.attr("gil_acquire_funcaddr").ptr()));
               py::gil_scoped_release gil_release;
diff --git a/tests/test_iostream.cpp b/tests/test_iostream.cpp
index e67f88a..e916150 100644
--- a/tests/test_iostream.cpp
+++ b/tests/test_iostream.cpp
@@ -37,7 +37,7 @@
     });
 
     m.def("captured_output", [](std::string msg) {
-        py::scoped_ostream_redirect redir(std::cout, py::module::import("sys").attr("stdout"));
+        py::scoped_ostream_redirect redir(std::cout, py::module_::import("sys").attr("stdout"));
         std::cout << msg << std::flush;
     });
 
@@ -46,7 +46,7 @@
             py::arg("msg"), py::arg("flush")=true);
 
     m.def("captured_err", [](std::string msg) {
-        py::scoped_ostream_redirect redir(std::cerr, py::module::import("sys").attr("stderr"));
+        py::scoped_ostream_redirect redir(std::cerr, py::module_::import("sys").attr("stderr"));
         std::cerr << msg << std::flush;
     });
 
@@ -65,8 +65,8 @@
     });
 
     m.def("captured_dual", [](std::string msg, std::string emsg) {
-        py::scoped_ostream_redirect redirout(std::cout, py::module::import("sys").attr("stdout"));
-        py::scoped_ostream_redirect redirerr(std::cerr, py::module::import("sys").attr("stderr"));
+        py::scoped_ostream_redirect redirout(std::cout, py::module_::import("sys").attr("stdout"));
+        py::scoped_ostream_redirect redirerr(std::cerr, py::module_::import("sys").attr("stderr"));
         std::cout << msg << std::flush;
         std::cerr << emsg << std::flush;
     });
diff --git a/tests/test_kwargs_and_defaults.cpp b/tests/test_kwargs_and_defaults.cpp
index 641ec88..7bda708 100644
--- a/tests/test_kwargs_and_defaults.cpp
+++ b/tests/test_kwargs_and_defaults.cpp
@@ -107,7 +107,7 @@
             return py::make_tuple(i, j, k, kwargs); },
             py::arg() /* positional */, py::arg("j") = -1 /* both */, py::kw_only(), py::arg("k") /* kw-only */);
 
-    m.def("register_invalid_kw_only", [](py::module m) {
+    m.def("register_invalid_kw_only", [](py::module_ m) {
         m.def("bad_kw_only", [](int i, int j) { return py::make_tuple(i, j); },
                 py::kw_only(), py::arg() /* invalid unnamed argument */, "j"_a);
     });
@@ -138,5 +138,5 @@
     // Make sure a class (not an instance) can be used as a default argument.
     // The return value doesn't matter, only that the module is importable.
     m.def("class_default_argument", [](py::object a) { return py::repr(a); },
-        "a"_a = py::module::import("decimal").attr("Decimal"));
+        "a"_a = py::module_::import("decimal").attr("Decimal"));
 }
diff --git a/tests/test_local_bindings.cpp b/tests/test_local_bindings.cpp
index 97c02db..c61e388 100644
--- a/tests/test_local_bindings.cpp
+++ b/tests/test_local_bindings.cpp
@@ -41,7 +41,7 @@
     // should raise a runtime error from the duplicate definition attempt.  If test_class isn't
     // available it *also* throws a runtime error (with "test_class not enabled" as value).
     m.def("register_local_external", [m]() {
-        auto main = py::module::import("pybind11_tests");
+        auto main = py::module_::import("pybind11_tests");
         if (py::hasattr(main, "class_")) {
             bind_local<LocalExternal, 7>(m, "LocalExternal", py::module_local());
         }
diff --git a/tests/test_methods_and_attributes.cpp b/tests/test_methods_and_attributes.cpp
index 11d4e7b..b6df41d 100644
--- a/tests/test_methods_and_attributes.cpp
+++ b/tests/test_methods_and_attributes.cpp
@@ -207,12 +207,12 @@
         // test_no_mixed_overloads
         // Raise error if trying to mix static/non-static overloads on the same name:
         .def_static("add_mixed_overloads1", []() {
-            auto emna = py::reinterpret_borrow<py::class_<ExampleMandA>>(py::module::import("pybind11_tests.methods_and_attributes").attr("ExampleMandA"));
+            auto emna = py::reinterpret_borrow<py::class_<ExampleMandA>>(py::module_::import("pybind11_tests.methods_and_attributes").attr("ExampleMandA"));
             emna.def       ("overload_mixed1", static_cast<py::str (ExampleMandA::*)(int, int)>(&ExampleMandA::overloaded))
                 .def_static("overload_mixed1", static_cast<py::str (              *)(float   )>(&ExampleMandA::overloaded));
         })
         .def_static("add_mixed_overloads2", []() {
-            auto emna = py::reinterpret_borrow<py::class_<ExampleMandA>>(py::module::import("pybind11_tests.methods_and_attributes").attr("ExampleMandA"));
+            auto emna = py::reinterpret_borrow<py::class_<ExampleMandA>>(py::module_::import("pybind11_tests.methods_and_attributes").attr("ExampleMandA"));
             emna.def_static("overload_mixed2", static_cast<py::str (              *)(float   )>(&ExampleMandA::overloaded))
                 .def       ("overload_mixed2", static_cast<py::str (ExampleMandA::*)(int, int)>(&ExampleMandA::overloaded));
         })
@@ -308,11 +308,11 @@
     m.attr("debug_enabled") = false;
 #endif
     m.def("bad_arg_def_named", []{
-        auto m = py::module::import("pybind11_tests");
+        auto m = py::module_::import("pybind11_tests");
         m.def("should_fail", [](int, UnregisteredType) {}, py::arg(), py::arg("a") = UnregisteredType());
     });
     m.def("bad_arg_def_unnamed", []{
-        auto m = py::module::import("pybind11_tests");
+        auto m = py::module_::import("pybind11_tests");
         m.def("should_fail", [](int, UnregisteredType) {}, py::arg(), py::arg() = UnregisteredType());
     });
 
diff --git a/tests/test_modules.cpp b/tests/test_modules.cpp
index c1475fa..897cf89 100644
--- a/tests/test_modules.cpp
+++ b/tests/test_modules.cpp
@@ -13,6 +13,7 @@
 
 TEST_SUBMODULE(modules, m) {
     // test_nested_modules
+    // This is intentionally "py::module" to verify it still can be used in place of "py::module_"
     py::module m_sub = m.def_submodule("subsubmodule");
     m_sub.def("submodule_func", []() { return "submodule_func()"; });
 
@@ -50,6 +51,7 @@
         .def_readwrite("a1", &B::a1)  // def_readonly uses an internal reference return policy by default
         .def_readwrite("a2", &B::a2);
 
+    // This is intentionally "py::module" to verify it still can be used in place of "py::module_"
     m.attr("OD") = py::module::import("collections").attr("OrderedDict");
 
     // test_duplicate_registration
@@ -60,7 +62,7 @@
         class Dupe3 { };
         class DupeException { };
 
-        auto dm = py::module("dummy");
+        auto dm = py::module_("dummy");
         auto failures = py::list();
 
         py::class_<Dupe1>(dm, "Dupe1");
diff --git a/tests/test_numpy_array.cpp b/tests/test_numpy_array.cpp
index c6bc5e0..753fa9f 100644
--- a/tests/test_numpy_array.cpp
+++ b/tests/test_numpy_array.cpp
@@ -22,7 +22,7 @@
 
 template <typename T>
 DtypeCheck get_dtype_check(const char* name) {
-    py::module np = py::module::import("numpy");
+    py::module_ np = py::module_::import("numpy");
     DtypeCheck check{};
     check.numpy = np.attr("dtype")(np.attr(name));
     check.pybind11 = py::dtype::of<T>();
@@ -133,7 +133,7 @@
 static int data_i = 42;
 
 TEST_SUBMODULE(numpy_array, sm) {
-    try { py::module::import("numpy"); }
+    try { py::module_::import("numpy"); }
     catch (...) { return; }
 
     // test_dtypes
diff --git a/tests/test_numpy_dtypes.cpp b/tests/test_numpy_dtypes.cpp
index f235831..c4ab02b 100644
--- a/tests/test_numpy_dtypes.cpp
+++ b/tests/test_numpy_dtypes.cpp
@@ -255,7 +255,7 @@
 struct B {};
 
 TEST_SUBMODULE(numpy_dtypes, m) {
-    try { py::module::import("numpy"); }
+    try { py::module_::import("numpy"); }
     catch (...) { return; }
 
     // typeinfo may be registered before the dtype descriptor for scalar casts to work...
diff --git a/tests/test_numpy_vectorize.cpp b/tests/test_numpy_vectorize.cpp
index 1f2de5f..aa8a881 100644
--- a/tests/test_numpy_vectorize.cpp
+++ b/tests/test_numpy_vectorize.cpp
@@ -17,7 +17,7 @@
 }
 
 TEST_SUBMODULE(numpy_vectorize, m) {
-    try { py::module::import("numpy"); }
+    try { py::module_::import("numpy"); }
     catch (...) { return; }
 
     // test_vectorize, test_docs, test_array_collapse
diff --git a/tests/test_pytypes.cpp b/tests/test_pytypes.cpp
index 9384c92..d38ea19 100644
--- a/tests/test_pytypes.cpp
+++ b/tests/test_pytypes.cpp
@@ -289,7 +289,7 @@
         py::print("no new line here", "end"_a=" -- ");
         py::print("next print");
 
-        auto py_stderr = py::module::import("sys").attr("stderr");
+        auto py_stderr = py::module_::import("sys").attr("stderr");
         py::print("this goes to stderr", "file"_a=py_stderr);
 
         py::print("flush", "flush"_a=true);
diff --git a/tests/test_stl_binders.cpp b/tests/test_stl_binders.cpp
index 8688874..1c0df98 100644
--- a/tests/test_stl_binders.cpp
+++ b/tests/test_stl_binders.cpp
@@ -117,7 +117,7 @@
     });
 
     // The rest depends on numpy:
-    try { py::module::import("numpy"); }
+    try { py::module_::import("numpy"); }
     catch (...) { return; }
 
     // test_vector_buffer_numpy
diff --git a/tests/test_virtual_functions.cpp b/tests/test_virtual_functions.cpp
index 4fc04ac..685d64a 100644
--- a/tests/test_virtual_functions.cpp
+++ b/tests/test_virtual_functions.cpp
@@ -187,7 +187,7 @@
 
 // Forward declaration (so that we can put the main tests here; the inherited virtual approaches are
 // rather long).
-void initialize_inherited_virtuals(py::module &m);
+void initialize_inherited_virtuals(py::module_ &m);
 
 TEST_SUBMODULE(virtual_functions, m) {
     // test_override
@@ -459,7 +459,7 @@
 };
 */
 
-void initialize_inherited_virtuals(py::module &m) {
+void initialize_inherited_virtuals(py::module_ &m) {
     // test_inherited_virtuals
 
     // Method 1: repeat