Building on Windows

Development on Microsoft Windows isn't really encouraged. The build environment isn't really conducive to development and many of the unit tests don't work. However, if you must...

GnuCash 3.0 and Later

The build system for GnuCash 2.7 and later supports Windows 7 and later. The procedure is a bit simpler than for GnuCash 2.6 and earlier and provides a somewhat easier to use development environment. That doesn't mean that we recommend that you use Windows for development: GnuCash is very much a Unix program and development is much easier in a Unix environment like Linux, BSD, or MacOS. Windows 10 and later users can use Windows Subsystem for Linux to easily set up a Linux environment that works quite well and the resulting GnuCash can be added to the Windows Start menu.

PowerShell

The build system relies heavily on Windows PowerShell.

Windows 7: The PowerShell version that ships with Windows 7 by default is too old. To build GnuCash on that platform a more recent version of PowerShell should be installed. PowerShell version 5.1 is known to work well.

Depending on your security settings you may need to enable running scripts on your computer. For this open a powershell with Administrator privilages and run:

set-executionpolicy unrestricted

Bootstrap the build environment

First download and run setup-mingw64.ps1. Depending on where you want to put the development tree you may need to run PowerShell as an administrator. Once you've downloaded the script start PowerShell. You can review the script's parameters with

help \path\to\setup-mingw64.ps1

For convenience they're

• target_dir: The root directory where the build environment will be installed. The default is c:\gcdev64, but you can put it anywhere you have write privilege.
• download_dir: Defaults to target_dir\downloads. There's no requirement to have it in target_dir.
• x86_64: Set this to $true if you want to build 64-bit binaries. The default is $false, and the developers do not often try to build 64-bit binaries so doing so isn't guaranteed to work nor are the developers much inclined to prioritize fixing it if it doesn't.

Note: The help command above will only work if the security settings of your system allow this script to be run. In addition to the set-executionpolicy command above you may have to run

unblock-file \path\to\setup-mingw64.ps1

before help will work.

Once setup-mingw64.ps1 is complete you will have an MSYS2 environment with all of the GnuCash dependencies that don't need to be built from source installed in it.

Running a build

Next open the Start menu and navigate to MSYS2 64Bit or MSYS2 32Bit; which you want will depend upon the bitness of your Windows version. If you specified x86_64 $true to setup-mingw64.ps1 you'll want to start the mingw64 shell, otherwise the mingw32 shell.

Note

Currently [2024-07] WebKitGtk is only availabe in 32-bit and won't link with a 64-bit GnuCash.

In that shell window navigate to the gnucash-on-windows.git directory in the target directory to specified to setup-mingw64.ps1. We'll use the default for the following examples.

  cd /c/gcdev64/src/gnucash-on-windows.git
  TARGET=gnucash-unstable jhbuild -f jhbuildrc build

One of the things setup-mingw64.ps1 did was checkout the rest of the gnucash-on-windows repository in target_dir/src/gnucash-on-windows.git. That contains a customization (python) script and a jhbuild moduleset. The customization script selects one of the three GnuCash branches to build based on the value of $TARGET; the possibilities are gnucash-stable (the default), gnucash-unstable (the unstable release git branch) and gnucash-releases, which builds GnuCash from the tarball specified in gnucash.modules instead of from a git branch.The first time jhbuild build command will build GnuCash, GnuCash Docs, and all of the dependencies that Mingw-w64 doesn't provide. After that it only builds modules that need rebuilding unless you tell it otherwise; see the jhbuild manual for details on controlling jhbuild.

You can start a subshell with the paths to hand-compile or run GnuCash from the command line with

TARGET=gnucash-unstable jhbuild -f jhbuildrc shell

This is convenient for development as one can navigate to the gnucash build directory and re-run CMake and make as necessary while developing. N.B. Be sure to use a programming editor that preserves line ending style; git can get really unhappy if you put the wrong kind of line endings into a file. To build a package for installation there's a PowerShell script called gnucash-on-windows.git\bundle-gnucash.ps1 and an automation script, gnucash-on-windows.git\buildserver\build_package.ps1 suitable for use with the Task Scheduler for periodic builds. Each includes documentation accessible with PowerShell's help command, e.g.

help bundle-gnucash.ps1

Note that build_package.ps1 also takes care of updating the gnucash-on-windows repository and that jhbuild build will update the gnucash repository; you can do so manually with git from within the Mingw shell. SSH works, just set up your ~/.ssh directory with the necessary keys and config file.

You may find the MSys2 Wiki and Mingw-w64 Documentation helpful.

Debugging a build

GDB can be used on windows without too much effort. Usually it's better to attach to an already running process instead of trying to launch directly under GDB. Ctrl+C does not work as well under GDB, however this site has a workaround: Workaround for GDB Ctrl C Interrupt

Microsoft's Visual Studio Code is a possibility to integrate with gnucash and gdb for debugging. The following launch.json file can be used to debug with gdb under vscode:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) launch",
            "type": "cppdbg",
            "request": "launch",
            "program": "C:\\gcdev64\\gnucash\\maint\\inst\\bin\\gnucash.exe",
            "args": [],
            "stopAtEntry": true,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": true,
            "MIMode": "gdb",
            "miDebuggerPath": "C:\\gcdev64\\msys2\\mingw32\\bin\\gdb.exe",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

Dependencies

The MSYS2 project that manages Mingw64 is phasing out the Mingw32 environment and this is having an impact on building GnuCash on Windows. One of our more significant dependencies, Guile, won't build in any of the MSYS2 supported 64-bit environments so switching to Mingw64 is not yet an option. setup_mingw64.ps1 installs the current workarounds, but if you've been using an environment for a while updating it will break building GnuCash unless you have the latest.

• International Components for Unicode, ICU, is not built for Mingw32. The last Mingw32 build is 1.76.1 from January 2025.
• Harfbuzz-ICU depends on ICU. The last Mingw32 build is 11.0.1 from April 2025.
• To use Harfbuzz-ICU you must also have the corresponding hafbuzz-11.0.1-2
• In September 2025 MSYS2 patched libxml2 in a binary-incompatible way and a dependency, libsoup-2.74.3.
• WebKitGtk was dropped entirely from Mingw64 several years ago and we've been building a package since. This is the latest one.

When the stars align correctly you can install any of those by copying the link and running

   pacman -U <link>

When the stars don't align you have to get the link with curl or your browser and use pacman -U on the downloaded file. When you do that notice that each file is accompanied by another file of the same name with .sig appended. That's a GPG signature for the file and pacman insists on having it. Download both files!

Note that libsoup and webkitgtk are maintained and signed by jralls. setup_mingw64.ps1 already installed his GPG public key in the MSYS2 keyring.

You'll want to stop pacman -Syu from replacing Harfbuzz with a newer version that will break Harfbuzz-ICU so create a file /etc/pacman.d/gnucash-ignores.pacman and add to it

  IgnorePkg = mingw-w64-i686-harfbuzz
  IgnorePkg = mingw-w64-i686-harfbuzz-icu
  IgnorePkg = mingw-w64-i686-icu

The last two are probably unnecessary but are cheap insurance.

GnuCash 2.6 and Earlier

GnuCash 2.6 is no longer being developed. This procedure is archival. Don't use it without good reason.

First read the README for the Windows Build Environment. You'll need to download and run bootstrap_win_dev.vbs, then adjust gnucash-on-windows.git/custom.sh to build what you want the way you want, and run

 gnucash-on-windows.sh/install.sh

to build the program.

You'll find a shell file, devrc.sh in gnucash-on-windows.git. Sourcing, not running, this file

 . gnucash-on-windows.git/devrc.sh

will set the necessary environment variables so that you can re-run the build script as usual in gnucash/build and run GnuCash from gnucash/inst/bin