This python script helps you build a full GTK library stack for Windows using Visual Studio. Currently, GTK 3 and GTK 4 are supported.
If you want to only run GTK on Windows and not build it yourself, you can download
a zip file from the latest release and unzip it to C:\gtk
.
It comes with GTK4, Cairo, PyGObject, Pycairo, GtkSourceView5, adwaita-icon-theme, and all of their dependencies.
Note however that these binaries are provided “AS IS”, WITHOUT WARRANTY OF ANY KIND. They just contain the output of our latest CI run. They are not tested, and we cannot commit to timely updates even for security issues. We strongly recommend to build your own binaries, especially if you plan to distribute them with your application or use them in production.
Finally, add GTK to your environmental variables with:
$env:Path = "C:\gtk\bin;" + $env:Path
$env:LIB = "C:\gtk\lib;" + $env:LIB
$env:INCLUDE = "C:\gtk\include;C:\gtk\include\cairo;C:\gtk\include\glib-2.0;C:\gtk\include\gobject-introspection-1.0;C:\gtk\lib\glib-2.0\include;" + $env:INCLUDE
If you are going to use PyGObject and Pycairo, you also need to use the gvsbuild generated wheels with your Python virtualenv in order to work around this PyGObject bug:
pip install --force-reinstall (Resolve-Path C:\gtk\wheels\PyGObject*.whl)
pip install --force-reinstall (Resolve-Path C:\gtk\wheels\pycairo*.whl)
The script supports multiple versions of Visual Studio - at the moment we are focusing on VS 2022, but we include projects for other versions, and we gladly accept patches.
The script focuses on GTK and the surrounding ecosystem (e.g. GStreamer). However, we are open to adding more libraries as long as the contributor takes on the responsibility for keeping it up to date. The supported projects are modules in the projects directory.
The script requires a working installation of Visual Studio for Windows Desktop, Python 3 and msys2. The script will download any additional tools required to build the libraries and will use them from a local directory, without any installation. As of today these tools include cmake, meson, ninja, nuget and perl.
The script fetches source tarballs for the projects from their original locations, however in some cases it might be necessary to host a patched tarball on GitHub. To ensure integrity of the downloaded files, the script checks the SHA256 hash of each download. Downloads are done using TLS, using SSL certificates provided by the system, but in case of error the download is tried again ignoring certificate errors.
First we need to install the prerequisites. There are two main options:
If you would prefer to use Chocolately instead of WinGet, you can skip this section and follow the Prerequisites with Chocolately steps.
WinGet is the Windows Package Manager and is available on Windows 11 and modern versions of Windows 10 (1809 / build 17763) as a part of the App Installer package in the Windows Store.
To setup a development environment in Windows install Git by executing as an administrator:
winget install --id Git.Git -e --source winget
Both of the development environments in the next steps need MSYS2 installed.
Install MSYS2:
Keep PowerShell open as administrator and execute:
winget install --id MSYS2.MSYS2 -e --source winget
With your admin PowerShell terminal:
winget install Microsoft.VisualStudio.2022.BuildTools -e --source winget --silent --override "--wait --quiet --add ProductLang En-us --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
Restart your computer following this installation.
Note: Visual Studio versions 2013 (not for all projects), 2015, 2017, 2019, and 2022 are currently supported.
With your admin PowerShell terminal:
winget install --id Python.Python.3.13 -e --source winget
Open a PowerShell terminal as a normal user and check the python version:
py -3.13 --version
If you already installed the prerequisites with WinGet, you can skip this section.
An alternative to WinGet is using Chocolately as a package manager in Windows.
To install it, open PowerShell as an administrator, then execute:
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
To run local scripts in follow-on steps, also execute
Set-ExecutionPolicy RemoteSigned
. This allows for local PowerShell scripts
to run without signing, but still requires signing for remote scripts.
To setup a development environment in Windows install Git by executing as an administrator:
choco install git
Both of the development environments in the next steps need MSYS2 installed.
Install MSYS2:
Keep PowerShell open as administrator and execute:
choco install msys2
With your admin PowerShell terminal:
choco install visualstudio2022-workload-vctools
Note: Visual Studio versions 2013 (not for all projects), 2015, 2017, 2019, and 2022 are currently supported.
With your admin PowerShell terminal:
choco install python312
Open a PowerShell terminal as a normal user and check the python version:
py -3.13 --version
The recommended way to install gvsbuild is with pipx. Open a new regular user PowerShell terminal and execute:
py -3.13 -m pip install --user pipx
py -3.13 -m pipx ensurepath
pipx install gvsbuild
Alternatively, you can also use git to clone the repository and install it. Open a new regular user PowerShell terminal and execute:
mkdir C:\gtk-build\github
cd C:\gtk-build\github
git clone https://github.com/wingtk/gvsbuild.git
cd C:\gtk-build\github\gvsbuild
python -m venv .venv
.\.venv\Scripts\activate.ps1
pip install .
In the same PowerShell terminal, execute:
gvsbuild build gtk3
Alternatively, if you want to build GTK 4, execute:
gvsbuild build gtk4
Grab a coffee, the build will take a few minutes to complete.
Path
row in the top list of variables. Click “New” to add a new item to the list.C:\gtk-build\gtk\x64\release\bin
You are now ready to use GTK!
Open Visual Studio and "Create a new project" using the "Empty Project" template
On the left, right click on "Source Files" and choose "Add", then "New Item..." and replace the name with main.c
Paste in the following contents, then save the file:
#include <gtk/gtk.h>
static void activate_cb(GtkApplication *app) {
GtkWidget *window = gtk_application_window_new(app);
gtk_widget_set_visible(window, true);
}
int main(int argc, char **argv) {
GtkApplication *app =
gtk_application_new("org.app", G_APPLICATION_DEFAULT_FLAGS);
g_signal_connect(app, "activate", G_CALLBACK(activate_cb), NULL);
return g_application_run(G_APPLICATION(app), argc, argv);
}
Go to your project's settings by right-clicking and choosing "Properties"
On the left, open "C/C++", then choose "Command Line".
pkg-config --cflags gtk4 --msvc-syntax
Still in the Visual Studio window, click on "Linker" and choose "Command Line". Do the same thing as the last step, except use the output of pkg-config --libs gtk4 --msvc-syntax
Click "OK"
In the top menu bar, click "Debug" and "Start Without Debugging"
See the fantastic gtk-rs
book.
You can skip the "Install GTK 4" step, as the above steps ^ covered that.
First, add GTK to your environment variables:
$env:LIB = "C:\gtk-build\gtk\x64\release\lib;" + $env:LIB
$env:INCLUDE = "C:\gtk-build\gtk\x64\release\include;C:\gtk-build\gtk\x64\release\include\cairo;C:\gtk-build\gtk\x64\release\include\glib-2.0;C:\gtk-build\gtk\x64\release\include\gobject-introspection-1.0;C:\gtk-build\gtk\x64\release\lib\glib-2.0\include;" + $env:INCLUDE
Next, add the --enable-gi
and --py-wheel
options like:
gvsbuild build --enable-gi --py-wheel gtk4 pygobject
Once that finishes, then you need to use the gvsbuild generated wheels with your Python virtualenv in order to work around this PyGObject bug:
pip install --force-reinstall (Resolve-Path C:\gtk-build\build\x64\release\pygobject\dist\PyGObject*.whl)
pip install --force-reinstall (Resolve-Path C:\gtk-build\build\x64\release\pycairo\dist\pycairo*.whl)
If you are going to use SVG icons with a GTK app, you need to also need to build librsvg
. Normally you want
to build GTK with gvsbuild build gtk4 adwaita-icon-theme
which will include librsvg and hicolor-icon-theme.
For more information about the possible commands run:
gvsbuild --help
To get detailed help on the build command run:
gvsbuild build --help
It is possible to set some parameters from a file, e.g. vs2015-release.pro, putting the @ character before the file name. The file contains the option, one per line, separated by a carriage return:
--vs-ver
14
--win-sdk
8.1
--configuration
release
Even if the format is not the easier to write or read in this way we eliminate the problem of escaping spaces is file names and directories. Then you can use it:
gvsbuild build @vs2015-release.pro gtk3-full
--clean
, if that fails, try
rebuilding it with --from-scratch
--ninja-opts -j2
option, where 2 is the number of cores.In addition to the setup instructions above, to build OpenSSL you also need the Visual C++ 2013 Redistributable Package installed. To install it, open PowerShell as administrator and execute:
choco install vcredist2013
Similar to other packages, you can build OpenSSL by executing:
gvsbuild build openssl
To see and analyze the dependency between the various projects, in text or in a Graphviz format, use the script deps.py:
gvsbuild deps --graph --gv-file test.gv
Without option a simple dependency of all the projects is printed, as usual with --help a summary of the options/commands is printed.
The following projects are using Gvsbuild for Windows GTK cross-platform support:
Are you using Gvsbuild? Please submit a Pull Request to add your app to the list.
This build script is licensed under the GPL2.0 license, see the COPYING file for the full text.
The binaries produced by the build script are licensed under the license terms of the project that is built (ie glib is LGPL so you can use glib.dll built with this script under the terms of LGPL).
Patches included in the repository are licensed under the license terms of the project they apply to.
This tool originated from a gtk-win32 PowerShell script created by the HexChat developers for building it for Windows. Although this project is now archived, you can explore the original project if you are interested in the history at https://github.com/hexchat/gtk-win32.
Compiling the GTK stack on MSVC would not be possible without the incredible work by Fan Chun-wei. If you are interested in more details of how this works, please see Compiling the GTK+ (and Clutter) stack using Visual C++ 2008 and later.