Pelican "ModuleNotFoundError" for a plugin in CI

By Daniel Zoghalchali·Latchkey

Pelican imports each plugin named in PLUGINS when it starts. A plugin that is referenced but not installed (or a renamed namespace plugin) raises ModuleNotFoundError before any content is generated.

What this error means

pelican fails on startup with "ModuleNotFoundError: No module named 'X'" where X is a configured plugin, ending the build.

ModuleNotFoundError: No module named 'pelican.plugins.sitemap'

  (referenced in PLUGINS in pelicanconf.py)

Common causes

The plugin package is not installed

PLUGINS lists a plugin whose package was never added to requirements, so a clean CI install does not have it.

A namespace plugin import path mismatch

Newer Pelican plugins live under pelican.plugins.*; an old or wrong import path no longer resolves.

How to fix it

Install the plugin and pin it

1. Add the plugin distribution to requirements.
2. Use the correct import name in PLUGINS.
3. Reinstall and re-run pelican.

pip install pelican-sitemap
# pelicanconf.py: PLUGINS = ['pelican.plugins.sitemap']

Match the import path to the plugin version

Confirm whether the plugin uses a namespace path or a legacy PLUGIN_PATHS directory, and configure accordingly.

PLUGINS = ['pelican.plugins.sitemap']

How to prevent it

• Keep every configured plugin in requirements.
• Use the namespace import path the plugin version expects.
• Install from a pinned requirements file in CI.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation