Install & Compatibility
Where this runs
tested against v0.5.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 31.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 32MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
glightbox
✓ plugins:
- glightbox
✗ from mkdocs_glightbox.plugin import LightboxPlugin # Not a direct Python import for user code
MkDocs plugins are configured in mkdocs.yml, not directly imported in Python user code. Add 'glightbox' to the 'plugins' section of your mkdocs.yml file to enable it.
To quickly get started, install the plugin and then enable it in your `mkdocs.yml` file under the `plugins` section. By default, it will automatically apply a lightbox effect to all images. For more advanced features like galleries, use the `data-gallery` attribute in your Markdown. Remember to explicitly list other desired plugins (like `search`) if you define a `plugins` section.
mkdocs.yml:
```yaml
site_name: My Docs with Lightbox
theme: material # Or any other MkDocs theme
plugins:
- search # Keep default search if desired
- glightbox:
touchNavigation: true
loop: false
effect: zoom
auto_caption: true
```
docs/index.md:
```markdown
# Welcome
This is an image with a lightbox effect:
This is another image, part of a gallery:
{ data-gallery="my-gallery" }
```
Debug
Known issues
breakingVersion 0.5.0 replaced the `regex` library with `selectolax` for HTML processing. While this improves performance and maintainability, any projects that previously relied on `regex` as an indirect dependency or had custom logic tied to its behavior might experience breakage.fixEnsure your environment has `selectolax>=0.3.29` installed. If you had custom HTML parsing, adapt it to use `selectolax` if direct interaction with the parsing backend was expected.
affects: >=0.5.0
gotchaWhen defining the `plugins` section in `mkdocs.yml`, MkDocs will override its default `search` plugin. To retain the search functionality, you must explicitly add `search` back to the `plugins` list alongside `glightbox`.fixModify your `mkdocs.yml` to include `search` like this:
```yaml
plugins:
- search
- glightbox
```
affects: All versions (MkDocs behavior)
gotchaBetween versions 0.5.1 and 0.5.2, the `selectolax` dependency was initially pinned to `0.3.29` (to avoid missing binary wheel issues) and then updated to `>=0.3.29` to support Python 3.14. This indicates potential sensitivity to `selectolax` versions, especially in specific Python environments.fixIf encountering installation issues, ensure your Python version is compatible and consider explicitly installing a known working `selectolax` version if problems persist. Upgrading `mkdocs-glightbox` to the latest version should resolve many dependency-related issues.
affects: 0.5.1, 0.5.2
gotchaThe default `width` option for the lightbox changed from `100%` to `auto` in version 0.3.6 to prevent a bug with zooming large images. If you rely on images filling the full width of the lightbox by default, you might need to explicitly set `width: 100%` in your configuration.fixTo restore the previous behavior, add `width: 100%` to your `glightbox` plugin configuration in `mkdocs.yml`:
```yaml
plugins:
- glightbox:
width: 100%
``` affects: >=0.3.6
gotchaVersion 0.4.0 introduced 'manual mode', allowing users to opt-in to the lightbox effect for specific images or pages. If `manual: true` is configured, images will no longer automatically have the lightbox effect unless they have the `on-glb` class or the page has `glightbox: true` metadata.fixIf you enabled `manual: true`, explicitly add `on-glb` to images (e.g., `{ .on-glb }`) or add `glightbox: true` to page metadata to enable the lightbox. Otherwise, ensure `manual` is set to `false` or omitted for automatic behavior. affects: >=0.4.0
Upgrade
Version history
0.5.2latest on PyPI · released Oct 23, 2025
Audit
Dependencies
selectolaxrequiredUsed for efficient HTML parsing and manipulation.