cairocffi issue - solution for windows-latest

[dornech]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Actions Runner Image

Discussion Details

Hi there,
I have an issue with an package for the windos platform and mkdocs. As I have to generate the documentation on a windows-latest image, I run into the well known issue with cairocffi DLLs not being found.
Does anybody know what to do in the respective GitHub action? I think it is just setting a path but I do not know what the correct path on the runner image is and how to set it in the GitHub action.
Thanks in advance.

[Tanishq-S-Dev05]

Hey 👋,
yeah, that’s a pretty common issue when running mkdocs on the windows-latest runner. The problem usually comes from the cairocffi / cairo DLLs not being in the PATH during the workflow.

A quick fix is to make sure the GTK/cairo binaries are installed and added to the PATH in your job. You can do something like this in your GitHub Action:

jobs:
build:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4

  - name: Set up Python
    uses: actions/setup-python@v5
    with:
      python-version: "3.10"

  - name: Install dependencies
    run: |
      python -m pip install --upgrade pip
      pip install mkdocs cairocffi

  - name: Add cairo DLLs to PATH
    run: |
      echo "C:\hostedtoolcache\windows\cairo\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

  - name: Build docs
    run: mkdocs build

If that path doesn’t exist in your runner, another option is to install GTK directly via Chocolatey before installing your Python deps:

• name: Install GTK (for cairocffi)
  run: choco install gtk-runtime -y

That usually solves the missing DLL issue because cairocffi then finds the cairo DLLs automatically.

So in short:

Make sure GTK/cairo is installed.

Add its bin folder to PATH in your workflow.

After that, mkdocs build should run fine on windows-latest. 🚀

[dornech]

Thanks, I wil try. I think @Kozea himself does this GTK3 instgallation step in his test script https://github.com/Kozea/cairocffi/blob/main/.github/workflows/tests.yml.

 - name: Install Gtk and DejaVu fonts (Windows)
        if: matrix.os == 'windows-latest'
        run: |
          C:\msys64\usr\bin\bash -lc 'pacman -S mingw-w64-x86_64-ttf-dejavu mingw-w64-x86_64-gtk3 --noconfirm'
          xcopy "C:\msys64\mingw64\share\fonts\TTF" "C:\Users\runneradmin\.fonts" /e /i
          echo "C:\msys64\mingw64\bin" | Out-File -FilePath $env:GITHUB_PATH
          rm C:\msys64\mingw64\bin\python.exe

[dornech]

Well, thanks for your thaughts. I get one step further i e the installation of dependencies works but I still get the "DLL not found error" in the build step of my action.
https://github.com/dornech/utils-mystuff-windows/actions/runs/18103541701/job/51512376067#step:7:24

[dornech]

I added the following to my GitHubAction file

        shell: powershell
        run: |
          echo "C:\msys64\mingw64\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
          Write-Host "GITHUB_PATH: $env:PATH"
          echo "CAIROCFFI_DLL_DIRECTORIES=C:\msys64\mingw64\bin" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
          Write-Host "CAIROCFFI_DLL_DIRECTORIES: $env:CAIROCFFI_DLL_DIRECTORIES"

I also included setting CAIROCFFI_DLL_DIRECTORIES as I found that elsewhere.
And I added a dump of the environment variables.

And now it is getting strange: in the latest run neither the path is updated nor the CAIROCFFI_DLL_DIRECTORIES. This is the output in the log

Run echo "C:\msys64\mingw64\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
  echo "C:\msys64\mingw64\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
  Write-Host "GITHUB_PATH: $env:PATH"
  echo "CAIROCFFI_DLL_DIRECTORIES=C:\msys64\mingw64\bin" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
  Write-Host "CAIROCFFI_DLL_DIRECTORIES: $env:CAIROCFFI_DLL_DIRECTORIES"
  shell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.EXE -command ". '{0}'"
  env:
    MSYSTEM: MINGW64
GITHUB_PATH: D:\a\_temp\setup-msys2;C:\Program Files\MongoDB\Server\7.0\bin;C:\vcpkg;C:\tools\zstd;C:\hostedtoolcache\windows\stack\3.7.1\x64;C:\cabal\bin;C:\\ghcup\bin;C:\mingw64\bin;C:\Program Files\dotnet;C:\Program Files\MySQL\MySQL Server 8.0\bin;C:\Program Files\R\R-4.4.2\bin\x64;C:\SeleniumWebDrivers\GeckoDriver;C:\SeleniumWebDrivers\EdgeDriver\;C:\SeleniumWebDrivers\ChromeDriver;C:\Program Files (x86)\sbt\bin;C:\Program Files (x86)\GitHub CLI;C:\Program Files\Git\bin;C:\Program Files (x86)\pipx_bin;C:\npm\prefix;C:\hostedtoolcache\windows\go\1.24.7\x64\bin;C:\hostedtoolcache\windows\Python\3.9.13\x64\Scripts;C:\hostedtoolcache\windows\Python\3.9.13\x64;C:\hostedtoolcache\windows\Ruby\3.3.9\x64\bin;C:\Program Files\OpenSSL\bin;C:\tools\kotlinc\bin;C:\hostedtoolcache\windows\Java_Temurin-Hotspot_jdk\17.0.16-8\x64\bin;C:\Program Files\ImageMagick-7.1.2-Q16-HDRI;C:\Program Files\Microsoft SDKs\Azure\CLI2\wbin;C:\ProgramData\kind;C:\ProgramData\Chocolatey\bin;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Windows\System32\OpenSSH\;C:\Program Files\PowerShell\7\;C:\Program Files\Microsoft\Web Platform Installer\;C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\;C:\Program Files\Microsoft SQL Server\150\Tools\Binn\;C:\Program Files\dotnet\;C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\;C:\Program Files (x86)\WiX Toolset v3.14\bin;C:\Program Files\Microsoft SQL Server\130\DTS\Binn\;C:\Program Files\Microsoft SQL Server\140\DTS\Binn\;C:\Program Files\Microsoft SQL Server\150\DTS\Binn\;C:\Program Files\Microsoft SQL Server\160\DTS\Binn\;C:\ProgramData\chocolatey\lib\pulumi\tools\Pulumi\bin;C:\Program Files\CMake\bin;C:\Strawberry\c\bin;C:\Strawberry\perl\site\bin;C:\Strawberry\perl\bin;C:\ProgramData\chocolatey\lib\maven\apache-maven-3.9.11\bin;C:\Program Files\Microsoft Service Fabric\bin\Fabric\Fabric.Code;C:\Program Files\Microsoft SDKs\Service Fabric\Tools\ServiceFabricLocalClusterManager;C:\Program Files\nodejs\;C:\Program Files\Git\cmd;C:\Program Files\Git\mingw64\bin;C:\Program Files\Git\usr\bin;C:\Program Files\GitHub CLI\;c:\tools\php;C:\Program Files (x86)\sbt\bin;C:\Program Files\Amazon\AWSCLIV2\;C:\Program Files\Amazon\SessionManagerPlugin\bin\;C:\Program Files\Amazon\AWSSAMCLI\bin\;C:\Program Files\Microsoft SQL Server\130\Tools\Binn\;C:\Program Files\mongosh\;C:\Program Files\LLVM\bin;C:\Program Files (x86)\LLVM\bin;C:\Users\runneradmin\.dotnet\tools;C:\Users\runneradmin\.cargo\bin;C:\Users\runneradmin\AppData\Local\Microsoft\WindowsApps
CAIROCFFI_DLL_DIRECTORIES: 

https://github.com/dornech/utils-mystuff-windows/actions/runs/18107935856/job/51527039152

But I think I have to do the dump in a subsequent step. Will try.

[dornech]

OK, separating steps makes the environment update working

[dornech]

Unfortunately the hints so far did not fix the problem.

[dornech]

News form my testings. I thought: let's search for the cairo libraries.

      - name: Log environment variable updates
        shell: powershell
        run: |
          Write-Host "GITHUB_PATH: $env:PATH"
          Write-Host "CAIROCFFI_DLL_DIRECTORIES: $env:CAIROCFFI_DLL_DIRECTORIES"
          Get-ChildItem -Path C:\ -Filter "*libcairo*.d*" -File -Recurse -ErrorAction SilentlyContinue

Result:

    Directory: C:\Program Files\Unity Hub\resources\app.asar.unpacked\node_modules\canvas\build\Release
Mode                 LastWriteTime         Length Name                                                                 
----                 -------------         ------ ----                                                                 
-a----         8/20/2025   3:16 PM        1240385 libcairo-2.dll                                                       
-a----         8/20/2025   3:16 PM          35859 libcairo-gobject-2.dll                    

https://github.com/dornech/utils-mystuff-windows/actions/runs/18143154171/job/51638737464

[dornech]

Hurray, with path "C:\Program Files\Unity Hub\resources\app.asar.unpacked\node_modules\canvas\build\Release" it works!

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[dornech]

Hi there, problem solved with own answer on Sep 30th based on further own testings, no further comments so marked as closed.