Sep 23, 2025
diff --git a/doc/source/changes.rst b/doc/source/changes.rst
 Changelog
 =========

 4.0.0
 =====

 GitPython will no longer throw an ImportError when no git executable can
 be found at import time. Instead, errors are deferred until the first
 attempt at using it. Consumers with special handling for
 the old ImportError behaviour should instead call `git.refresh` and handle
 GitCommandNotFoundErrors themselves.

 See the following for all changes.
 https://github.com/gitpython-developers/GitPython/releases/tag/4.0.0


 3.1.45
 ======

diff --git a/git/__init__.py b/git/__init__.py
    GIT_OK = True


 try:
    refresh()
 except Exception as _exc:
    raise ImportError("Failed to initialize: {0}".format(_exc)) from _exc

 # } END initialize git executable path
diff --git a/git/cmd.py b/git/cmd.py
                    if mode in warn:
                        _logger.critical(err)
                    else:
                        raiseImportError(err)
                        raiseGitCommandNotFound(new_git,err)
                else:
                    err = dedent(
                        """\
            default (especially ``as_process = False``, ``stdout_as_string = True``) and
            return :class:`str`.
        """
        if not self.GIT_PYTHON_GIT_EXECUTABLE:
            self.refresh()
        # Handle optional arguments prior to calling transform_kwargs.
        # Otherwise these'll end up in args, which is bad.
        exec_kwargs = {k: v for k, v in kwargs.items() if k in execute_kwargs}
diff --git a/test/__init__.py b/test/__init__.py
 #
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 #
 import git

 git.refresh()
diff --git a/test/test_git.py b/test/test_git.py
            Git.GIT_PYTHON_GIT_EXECUTABLE = None  # Simulate startup.

            with mock.patch.dict(os.environ, env_vars):
                with self.assertRaisesRegex(ImportError, r"\ABad git executable.\n"):
                with self.assertRaisesRegex(GitCommandNotFound, r"Bad git executable."):
                    refresh()

    def test_initial_refresh_from_good_absolute_git_path_env(self):
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,6 +2,19 @@
		Changelog
		=========

		4.0.0
		=====

		GitPython will no longer throw an ImportError when no git executable can
		be found at import time. Instead, errors are deferred until the first
		attempt at using it. Consumers with special handling for
		the old ImportError behaviour should instead call `git.refresh` and handle
		GitCommandNotFoundErrors themselves.

		See the following for all changes.
		https://github.com/gitpython-developers/GitPython/releases/tag/4.0.0


		3.1.45
		======

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -292,9 +292,4 @@ def refresh(path: Optional[PathLike] = None) -> None:
		GIT_OK = True


		try:
		refresh()
		except Exception as _exc:
		raise ImportError("Failed to initialize: {0}".format(_exc)) from _exc

		# } END initialize git executable path
Original file line number	Diff line number	Diff line change
Expand Up		@@ -857,7 +857,7 @@ def refresh(cls, path: Union[None, PathLike] = None) -> bool:
		if mode in warn:
		_logger.critical(err)
		else:
		raiseImportError(err)
		raiseGitCommandNotFound(new_git,err)
		else:
		err = dedent(
		"""\
Expand DownExpand Up		@@ -1575,6 +1575,8 @@ def _call_process(
		default (especially ``as_process = False``, ``stdout_as_string = True``) and
		return :class:`str`.
		"""
		if not self.GIT_PYTHON_GIT_EXECUTABLE:
		self.refresh()
		# Handle optional arguments prior to calling transform_kwargs.
		# Otherwise these'll end up in args, which is bad.
		exec_kwargs = {k: v for k, v in kwargs.items() if k in execute_kwargs}
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,3 +2,7 @@
		#
		# This module is part of GitPython and is released under the
		# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
		#
		import git

		git.refresh()
Original file line number	Diff line number	Diff line change
Expand Up		@@ -434,7 +434,7 @@ def test_initial_refresh_from_bad_git_path_env_error(self, case):
		Git.GIT_PYTHON_GIT_EXECUTABLE = None # Simulate startup.

		with mock.patch.dict(os.environ, env_vars):
		with self.assertRaisesRegex(ImportError, r"\ABad git executable.\n"):
		with self.assertRaisesRegex(GitCommandNotFound, r"Bad git executable."):
		refresh()

		def test_initial_refresh_from_good_absolute_git_path_env(self):
Expand Down