As of 9 February 2026, we had to lock setuptools to < v81 to maintain the availability of pkg_resources because docxcompose, a dependency of docxtpl, requires it. Limiting setuptools is a temporary fix that cannot be maintianed long-term. There are few issues:
- The
docxcompose project has not been active in several years.
- The
docxtpl project tried to resolve this by making docxcompose an optional dependency, but it is not optional for Ghostwriter (the new_subdoc() method requires it).
- In January 2026, the
docxtpl maintainer announced they are looking to hand-off the project.
It is unlikely this issue will be sorted out downstream with the dependencies. Other contributors have started a fork of docxcompose (docxcompose3) that resolves the above issue, but docxtpl does not use it. We have also had issues like this in the past with docxtpl where a release removed or broke a feature we needed.
The best solution may be evaluating the fork of docxcompose and forking docxtpl (like we have done for python-docx) and changing our requirements to pull our forks. This allows us to customize the projects and control releases. However, this does add some overhead.
We will keep tabs on how this issue or is not resolved in the coming weeks and determine the best way forward.
As of 9 February 2026, we had to lock
setuptoolsto < v81 to maintain the availability ofpkg_resourcesbecausedocxcompose, a dependency ofdocxtpl, requires it. Limitingsetuptoolsis a temporary fix that cannot be maintianed long-term. There are few issues:docxcomposeproject has not been active in several years.docxtplproject tried to resolve this by makingdocxcomposean optional dependency, but it is not optional for Ghostwriter (thenew_subdoc()method requires it).docxtplmaintainer announced they are looking to hand-off the project.It is unlikely this issue will be sorted out downstream with the dependencies. Other contributors have started a fork of
docxcompose(docxcompose3) that resolves the above issue, butdocxtpldoes not use it. We have also had issues like this in the past withdocxtplwhere a release removed or broke a feature we needed.The best solution may be evaluating the fork of
docxcomposeand forkingdocxtpl(like we have done forpython-docx) and changing our requirements to pull our forks. This allows us to customize the projects and control releases. However, this does add some overhead.We will keep tabs on how this issue or is not resolved in the coming weeks and determine the best way forward.