Version requirements on dependencies of pillow and cairosvg for imaging install

[monodera]

I'm wondering if the dependencies on the imaging modules can be changed from

[project.optional-dependencies]

imaging = [
  "pillow~=10.2",
  "cairosvg~=2.6"
]

to something like the following?

[project.optional-dependencies]

imaging = [
  "pillow>=10.2",
  "cairosvg>=2.6"
]

I'm using MkDocs with the material template within the docs directory in an app's repository, and the dependencies conflict with other requirements which requests more recent versions, e.g., pillow>=11.1.0 (and Python 3.11+).

[alexvoss]

Depending on what build system you are using, you can configure different environments for building your code versus building the documentation. Hatch, for example, supports multiple environments. Hope this helps.

Note that I am not commenting on the question whether the version definition could or should be changed but it is a good idea to separate the dependencies in any case, I think.

[monodera]

Thanks! I will look into it.

I'm currently using PDM for the project now, which allows to put a dependency of editable git installation. I don't think it's supported in general.

[squidfunk]

Thanks for suggesting. So we want to stick to semantic versioning, in order to keep older versions of Material for MkDocs installable, and open-ended version ranges eventually break all prior versions, so just using >= should always be a last resort. We can definitely up the versions if they support our Python version range (3.8 and above), or we can also include ~=11.0. For Cairo, I think this is not necessary.

[squidfunk]

I'm afraid I'm not sure what you're referring to. All required dependencies have semantic version requirements, except for the mkdocs-git-committers-plugin-2, which we should definitely check if we can switch to ~= as well.

mkdocs-material/requirements.txt

Lines 21 to 38 in 08fd869

	# Requirements for core
	jinja2~=3.1
	markdown~=3.2
	mkdocs~=1.6
	mkdocs-material-extensions~=1.3
	pygments~=2.16
	pymdown-extensions~=10.2
	# Requirements for plugins
	babel~=2.10
	colorama~=0.4
	paginate~=0.5
	backrefs~=5.7.post1
	requests~=2.26
	# Temporarily pin click until this is resolved in MkDocs, see
	# https://github.com/mkdocs/mkdocs/issues/4014#issuecomment-3146508306
	click<8.2.2

mkdocs-material/pyproject.toml

Lines 55 to 68 in 08fd869

	[project.optional-dependencies]
	recommended = [
	"mkdocs-minify-plugin~=0.7",
	"mkdocs-redirects~=1.2",
	"mkdocs-rss-plugin~=1.6"
	]
	git = [
	"mkdocs-git-committers-plugin-2>=1.1,<3",
	"mkdocs-git-revision-date-localized-plugin~=1.2,>=1.2.4"
	]
	imaging = [
	"pillow~=10.2",
	"cairosvg~=2.6"
	]

Might I ask you to investigate which version of Pillow we would need to update to? With that information we can assess whether we change to 11 (Python 3.8 still supported), or add 11 as an additional range.

[pawamoy]

@squidfunk If at some point your team would like to lift these constraints, note that modern tools like uv and PDM allow resolving versions up to a specific date:

• https://docs.astral.sh/uv/concepts/resolution/#reproducible-resolutions
• https://pdm-project.org/en/latest/usage/lockfile/#exclude-packages-newer-than-specific-date

That means a bit more work for users on older versions of mkdocs-material, but that also prevents conflicts for up-to-date users.

@monodera On the user-side only, uv and PDM can once again help with their ability to override dependencies, assuming mkdocs-material actually work with more recent versions of pillow, etc.:

• https://docs.astral.sh/uv/concepts/resolution/#dependency-overrides
• https://pdm-project.org/en/latest/usage/dependency/#dependency-overrides

[squidfunk]

Ah, that's a nice and useful feature, thanks for noting! Regardless, keeping semantic versioning allows Material for MkDocs to make backward incompatible changes (e.g. drop browser support for ancient versions, as we did in v5), and users can still use v4 if they need it. However, I also understand that those requirements might be limiting at times, which is why we should update them when we run into problems like this, so happy to accept a PR as mentioned in #8379 (reply in thread)

[monodera]

I'm afraid I'm not sure what you're referring to. All required dependencies have semantic version requirements, except for the mkdocs-git-committers-plugin-2, which we should definitely check if we can switch to ~= as well.

Thanks for the clarification. Maybe I was looking at somewhere different.

Might I ask you to investigate which version of Pillow we would need to update to? With that information we can assess whether we change to 11 (Python 3.8 still supported), or add 11 as an additional range.

I will also talk to the maintainer of the other package if they could lower the version requirement for Piillow on their side (I believe at least 11.0.0 would work). Pillow has dropped Python 3.8 support at 11.0.0, so changing to 11.x.x means to drop the Python 3.8 support of mkdocs-material.

[monodera]

@monodera On the user-side only, uv and PDM can once again help with their ability to override dependencies, assuming mkdocs-material actually work with more recent versions of pillow, etc.:

* https://docs.astral.sh/uv/concepts/resolution/#dependency-overrides

* https://pdm-project.org/en/latest/usage/dependency/#dependency-overrides

Thank you for the suggestion. Now I understand why there is kind of feature. I'll try this for a short-term mitigation.