Building ESP-IDF Docs - libxcb.dll Error (v5.4.1, Python 3.13.3 on Windows)
Posted: Tue Jun 03, 2025 2:51 pm
Hey everyone,
I'm trying to build the ESP-IDF documentation (v5.4.1) on Windows, following all the official steps including setting up the environment and installing Doxygen.
After running export.bat and then build-docs -l en in the docs directory, the build process fails with an OSError: cannot load library 'libxcb.dll': error 0x7e. It also mentions ctypes.util.find_library() couldn't locate it.
It seems to be related to cairosvg and xcffib trying to load this DLL.
Has anyone encountered this issue when building ESP-IDF docs? Any tips on how to resolve this libxcb.dll dependency on Windows?
Full traceback is in the comments if needed!
Thanks in advance for any help!
I'm trying to build the ESP-IDF documentation (v5.4.1) on Windows, following all the official steps including setting up the environment and installing Doxygen.
After running export.bat and then build-docs -l en in the docs directory, the build process fails with an OSError: cannot load library 'libxcb.dll': error 0x7e. It also mentions ctypes.util.find_library() couldn't locate it.
It seems to be related to cairosvg and xcffib trying to load this DLL.
Has anyone encountered this issue when building ESP-IDF docs? Any tips on how to resolve this libxcb.dll dependency on Windows?
Full traceback is in the comments if needed!
Thanks in advance for any help!
Code: Select all
C:\Espressif\frameworks\esp-idf-v5.4.1>export.bat
Activating ESP-IDF 5.4
Setting IDF_PATH to 'C:\Espressif\frameworks\esp-idf-v5.4.1'.
* Checking python version ... 3.13.3
* Checking python dependencies ... OK
* Deactivating the current ESP-IDF environment (if any) ... OK
* Establishing a new ESP-IDF environment ... OK
* Identifying shell ... cmd.exe
* Detecting outdated tools in system ... Found tools that are not used by active ESP-IDF version.
For removing old versions of idf-driver, idf-python-wheels use command 'python.exe C:\Espressif\frameworks\esp-idf-v5.4.1\tools\idf_tools.py uninstall'
To free up even more space, remove installation packages of those tools.
Use option python.exe C:\Espressif\frameworks\esp-idf-v5.4.1\tools\idf_tools.py uninstall --remove-archives.
Done! You can now compile ESP-IDF projects.
Go to the project directory and run:
idf.py build
C:\Espressif\frameworks\esp-idf-v5.4.1>cd docs
C:\Espressif\frameworks\esp-idf-v5.4.1\docs>build-docs -l en
Building without a target
Will use 1 parallel builds and 1 jobs per build
[{'build_dir': 'C:\\Espressif\\frameworks\\esp-idf-v5.4.1\\docs\\_build\\en\\generic', 'source_dir': 'C:\\Espressif\\frameworks\\esp-idf-v5.4.1\\docs\\en', 'language': 'en', 'target': 'generic', 'sphinx_parallel_jobs': 1, 'builders': ['html'], 'input_docs': [''], 'doxyfile_dir': '.', 'project_path': '../'}]
Building in build_dir: C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic
Running 'C:\Espressif\python_env\idf5.4_py3.13_env\Scripts\python.exe -u -m sphinx.cmd.build -j 1 -b html -d C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\doctrees -w sphinx-warning-log.txt -v -D docs_to_build= -D config_dir=C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\esp_docs -D doxyfile_dir=C:\Espressif\frameworks\esp-idf-v5.4.1\docs -D project_path=C:\Espressif\frameworks\esp-idf-v5.4.1 C:\Espressif\frameworks\esp-idf-v5.4.1\docs\en C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\html'
en/generic: Running Sphinx v7.1.2
en/generic: Version: v5.4.1 Release: v5.4.1
en/generic: Git commit ID: 4c2820d377
en/generic: Git tag: v5.4.1
en/generic: Git commit ID: 4c2820d377
en/generic: Git tag: v5.4.1
en/generic: Adding copy buttons to code blocks...
en/generic:
en/generic: Traceback (most recent call last):
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\cmd\build.py", line 285, in build_main
en/generic: app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
en/generic: args.doctreedir, args.builder, args.confoverrides, args.status,
en/generic: args.warning, args.freshenv, args.warningiserror,
en/generic: args.tags, args.verbosity, args.jobs, args.keep_going,
en/generic: args.pdb)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 229, in __init__
en/generic: self.setup_extension(extension)
en/generic: ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 402, in setup_extension
en/generic: self.registry.load_extension(self, extname)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\registry.py", line 441, in load_extension
en/generic: mod = import_module(extname)
en/generic: File "C:\Users\HP\AppData\Local\Programs\Python\Python313\Lib\importlib\__init__.py", line 88, in import_module
en/generic: return _bootstrap._gcd_import(name[level:], package, level)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
en/generic: File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
en/generic: File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
en/generic: File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
en/generic: File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
en/generic: File "<frozen importlib._bootstrap_external>", line 1026, in exec_module
en/generic: File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom.py", line 15, in <module>
en/generic: from .wavedrom_render_image import render_wavedrom_image
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom_render_image.py", line 6, in <module>
en/generic: import cairosvg
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\__init__.py", line 26, in <module>
en/generic: from . import surface # noqa isort:skip
en/generic: ^^^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\surface.py", line 9, in <module>
en/generic: import cairocffi as cairo
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\__init__.py", line 18, in <module>
en/generic: from .ffi import ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\ffi.py", line 22, in <module>
en/generic: from xcffib.ffi import ffi as xcb_ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\xcffib\__init__.py", line 35, in <module>
en/generic: lib = ffi.dlopen(soname)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 150, in dlopen
en/generic: lib, function_cache = _make_ffi_library(self, name, flags)
en/generic: ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 834, in _make_ffi_library
en/generic: backendlib = _load_backend_lib(backend, libname, flags)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic:
en/generic: Exception occurred:
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic: The full traceback has been saved in C:\Users\HP\AppData\Local\Temp\sphinx-err-4k7usn30.log, if you want to report the issue to the developers.
en/generic: Please also report this if it was a user error, so that a better error message can be provided next time.
en/generic: A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\doxygen-warning-log.txt not generated
en/generic: Build failed due to new/different warnings (C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\sphinx-warning-log.txt):
en/generic: Traceback (most recent call last):
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\cmd\build.py", line 285, in build_main
en/generic: app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
en/generic: args.doctreedir, args.builder, args.confoverrides, args.status,
en/generic: args.warning, args.freshenv, args.warningiserror,
en/generic: args.tags, args.verbosity, args.jobs, args.keep_going,
en/generic: args.pdb)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 229, in __init__
en/generic: self.setup_extension(extension)
en/generic: ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\application.py", line 402, in setup_extension
en/generic: self.registry.load_extension(self, extname)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinx\registry.py", line 441, in load_extension
en/generic: mod = import_module(extname)
en/generic: File "C:\Users\HP\AppData\Local\Programs\Python\Python313\Lib\importlib\__init__.py", line 88, in import_module
en/generic: return _bootstrap._gcd_import(name[level:], package, level)
en/generic: ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
en/generic: File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
en/generic: File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
en/generic: File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
en/generic: File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
en/generic: File "<frozen importlib._bootstrap_external>", line 1026, in exec_module
en/generic: File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom.py", line 15, in <module>
en/generic: from .wavedrom_render_image import render_wavedrom_image
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\sphinxcontrib\wavedrom_render_image.py", line 6, in <module>
en/generic: import cairosvg
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\__init__.py", line 26, in <module>
en/generic: from . import surface # noqa isort:skip
en/generic: ^^^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairosvg\surface.py", line 9, in <module>
en/generic: import cairocffi as cairo
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\__init__.py", line 18, in <module>
en/generic: from .ffi import ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cairocffi\ffi.py", line 22, in <module>
en/generic: from xcffib.ffi import ffi as xcb_ffi
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\xcffib\__init__.py", line 35, in <module>
en/generic: lib = ffi.dlopen(soname)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 150, in dlopen
en/generic: lib, function_cache = _make_ffi_library(self, name, flags)
en/generic: ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 834, in _make_ffi_library
en/generic: backendlib = _load_backend_lib(backend, libname, flags)
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic: Exception occurred:
en/generic: File "C:\Espressif\python_env\idf5.4_py3.13_env\Lib\site-packages\cffi\api.py", line 829, in _load_backend_lib
en/generic: raise OSError(msg)
en/generic: OSError: cannot load library 'libxcb.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libxcb.dll'
en/generic: The full traceback has been saved in C:\Users\HP\AppData\Local\Temp\sphinx-err-4k7usn30.log, if you want to report the issue to the developers.
en/generic: Please also report this if it was a user error, so that a better error message can be provided next time.
en/generic: A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
en/generic: (Check files sphinx-known-warnings.txt and C:\Espressif\frameworks\esp-idf-v5.4.1\docs\_build\en\generic\sphinx-warning-log.txt for full details.)
[4]
The following language/target combinations failed to build:
language: en, target: generic, errcode: 4