A submodule is a foreign repository that is embedded within a dedicated subdirectory of the repositories tree.

class pygit2.Repository(path: str | None = None, flags: RepositoryOpenFlag = RepositoryOpenFlag.DEFAULT)

listall_submodules() list[str]

Return a list with all submodule paths in the repository.

The Submodule type

class pygit2.Submodule
property branch

Branch that is to be tracked by the submodule.

property head_id

Head of the submodule.

init(overwrite: bool = False)

Just like “git submodule init”, this copies information about the submodule into “.git/config”.



By default, existing submodule entries will not be overwritten, but setting this to True forces them to be updated.

property name

Name of the submodule.


Open the repository for a submodule.

property path

Path of the submodule.

reload(force: bool = False)

Reread submodule info from config, index, and HEAD.

Call this to reread cached submodule information for this submodule if you have reason to believe that it has changed.



Force reload even if the data doesn’t seem out of date

update(init: bool = False, callbacks: RemoteCallbacks = None)

Update a submodule. This will clone a missing submodule and checkout the subrepository to the commit specified in the index of the containing repository. If the submodule repository doesn’t contain the target commit (e.g. because fetchRecurseSubmodules isn’t set), then the submodule is fetched using the fetch options supplied in options.



If the submodule is not initialized, setting this flag to True will initialize the submodule before updating. Otherwise, this will raise an error if attempting to update an uninitialized repository.


Optional RemoteCallbacks to clone or fetch the submodule.

property url

URL of the submodule.