For the most part, following the official GitHub guide https://github.com/Deltares/Delft3D/blob/main/doc/compiling_Windows.md works without problems, but this article summarizes the points where I got stuck.

The Delft3D 4 Suite GUI package does not include the computational kernels. When you launch the GUI, you get the following error and nothing starts.

couldn't read file ".../kernels/x64/bin/create_config_xml.tcl": no such file or directory

This is not a bug but by design: users have to build the kernels from source themselves. This article describes the steps I took to get the build working on Windows, and how I dealt with the errors I encountered along the way.

1. Setting up the environment

Item	Choice
Visual Studio	2022 (not 2026)
Intel oneAPI	Fortran Compiler / MPI Library / Math Kernel Library, 2024.2 recommended
Cygwin (64-bit)	Installed in `C:\cygwin64`, with `make` and `python3` explicitly selected
Python environment	uv (installs Python and Conan 2 into a virtual environment)
Other	CMake, Git

Visual Studio

In addition to the "Desktop development with C++" workload, check the following individual components. They are not installed by default, and their absence causes link errors later on.

C++/CLI support for v143 build tools
C++ MFC for v143 build tools (x86 & x64)
The latest Windows SDK

Use VS2022, not VS2026. As the Conan profile name delft3d_windows_msvc_194_v3 suggests (194 = VS2022 / v143 toolset), the combination Deltares tests is VS2022 + oneAPI 2024.2. The third-party libraries are also compiled with this combination. VS2022 can coexist with VS2026, so there is no need to uninstall VS2026.

Note

Reference: https://kashiwaba-yuki.com/windows-visualstudio-download (in Japanese)

As of September 2026, Community editions of older (non-latest) Visual Studio versions can no longer be downloaded from the official website.
They are available from the following links:

Visual Studio 2017 Community: https://aka.ms/vs/15/release/vs_community.exe
Visual Studio 2019 Community: https://aka.ms/vs/16/release/vs_community.exe
Visual Studio 2022 Community: https://aka.ms/vs/17/release/vs_community.exe

Intel oneAPI

Install VS2022 first, then oneAPI. oneAPI's Visual Studio integration is applied only to the VS versions present at the time of installation. If oneAPI is already installed, run Modify from "Apps & features" and select VS2022 as the integration target.

How to verify: if "Fortran" appears in the language dropdown on VS2022's "Create a new project" screen, the integration succeeded.

Cygwin

The configure script of the dependency PETSc is a Unix shell script, so it does not run natively on Windows. The Conan recipe runs it through Cygwin's bash.

make and python3 are not installed by default. On the package selection screen of setup-x86_64.exe, set View to "Full" and click the New column to select a version. If it stays at Skip, the package will not be installed.

2. Building

Working directory

C:\checkouts\Delft3D

Do not build under a cloud-synced folder (Dropbox, OneDrive, etc.). The build creates and deletes a huge number of intermediate files, and the sync process locks files, causing mysterious failures. You are also more likely to hit the path length limit. Use a short local path.

Getting the source

git clone https://github.com/Deltares/Delft3D.git C:\checkouts\Delft3D

Python environment (uv)

I set up the Python environment with uv, as in the official instructions. There is no need to install Conan separately with the system Python or pip: uv creates a virtual environment (.venv) in the repository root and installs all required packages, including Conan 2, in one go.

cd C:\checkouts\Delft3D
uv sync
.venv\Scripts\activate

Run all subsequent python / conan commands with this virtual environment activated. If you forget to activate it, the system Python or a different version of Conan will be invoked, and the profile and remote settings will not match. To be sure, check that where python and where conan list the .venv paths first.

Note that because the build is run from the oneAPI command prompt described below, you need to run .venv\Scripts\activate again every time you open a new prompt (alternatively, you can use uv run python ...).

Initializing Conan

With the virtual environment activated, initialize Conan.

python run_conan.py initialize external

external is for developers outside Deltares. deltares is for Deltares' internal Nexus; if you run it from outside, the connection to internal-artifacts.deltares.nl times out and the build stalls.

After initialization, check the remotes.

conan remote list

The expected output is this single line. If an internal remote is still enabled, disable it with conan remote disable <name>.

local-recipes: C:\checkouts\Delft3D\conan [local-recipes-index, Enabled: True]

Setting for environments whose system code page is not UTF-8 (important)

set CL=/utf-8

On environments whose system code page is not UTF-8, such as Japanese, Chinese, or Korean Windows, the dependency builds fail unless you set this. As an example from a Japanese environment (CP932), compiling expat produces the following errors:

random_rand_s.c(1,1): warning C4819: The file contains a character that cannot be represented in the current code page (932). Save the file in Unicode format to prevent data loss
random_rand_s.c(47,1): error C1020: unexpected #endif

The source files are UTF-8 (without BOM), but MSVC reads files without a BOM using the system locale's code page (932 for Japanese). The byte sequences of non-ASCII characters in the copyright notice are misinterpreted, swallowing the following characters and breaking the matching of preprocessor directives. error C1020 is the consequence, not the cause.

Double-byte code pages such as CP932 (Japanese), CP936 (Simplified Chinese), CP949 (Korean), and CP950 (Traditional Chinese) are particularly affected. Single-byte code pages such as CP1252 (Western European) are less likely to lead to the same error, but they can still cause garbled characters and warnings, so it is safest to set this on any non-UTF-8 environment.

MSVC reads the CL environment variable at startup and prepends it to the command line, so it applies to every cl.exe invocation. You can also specify the flag via tools.build:cflags in the Conan profile, but some packages such as PETSc do not receive flags through Conan, so the environment variable is more reliable.

Running the build

Run the build from "Intel oneAPI command prompt for Intel 64 for Visual Studio 2022" in the Start menu. A regular cmd or PowerShell does not inherit the Intel / Visual Studio environment variables.

set CL=/utf-8
cd C:\checkouts\Delft3D
.venv\Scripts\activate
python build.py --build --build-dependencies --config d3d4-suite > build.log 2>&1

--build-dependencies is needed only for the first build (it builds PETSc and other dependencies locally). The first build takes on the order of several hours, but from the second time on the Conan cache kicks in and the time is greatly reduced.

Redirect the output to a file. If output goes directly to the console and QuickEdit Mode is enabled, accidentally clicking the window switches it to selection mode, which blocks the output and stalls the entire process. If the build stops in the middle of a line, or stops at a different place each time, suspect this. If it stalls in the console, press Enter or Esc to resume.

3. Deploying the kernels

When the build succeeds, an install_d3d4-suite folder is generated. Create kernels\x64 in the GUI installation directory and copy its contents there as is.

C:\Program Files\Deltares\Delft3D 4.07.02\kernels\x64\
                                            ├─ bin\
                                            └─ share\

Deltares' official instructions say to "copy bin, lib, and share", but that is a general description that covers Linux and the FM Suite as well. On Windows, shared libraries are placed in bin as .dll files, so the lib folder may not be generated. lib contains import libraries for linking, which are not needed to run computations, so this is not a problem. If bin contains d_hydro.exe and libflow2d3d.dll, everything is fine.

Once kernels\x64\bin\create_config_xml.tcl exists, you are done. You can now run computations from the GUI.

4. Troubleshooting quick reference

Symptom	Cause	Fix
`Conan profile ... not found`	Conan not initialized	`python run_conan.py initialize external`
`conan` not found / settings not applied	uv virtual environment not activated	`.venv\Scripts\activate`, check with `where conan`
`internal-artifacts.deltares.nl` timeout	Internal remote enabled	`conan remote disable`
PETSc `Error 127`	bash / make / python3 not found	Add packages to Cygwin, check `tools.microsoft.bash:path` in the profile
`error C1020: unexpected #endif`	UTF-8 source misread with the system code page (CP932, etc.)	`set CL=/utf-8`
Stalls in the middle of a line	Console QuickEdit Mode	Press Enter / redirect the log to a file
Stalls at a different place each time	Cygwin fork failure	Run `rebaseall` with administrator privileges
Build is extremely slow	Defender scanning	Add exclusions

The real cause is recorded not in the Python traceback but in the logs under C:\Users\<user>\.conan2\p\b\<package>\b, or in the redirected build.log. Addressing only the surface of an error will take you the long way around.

Summary

The common pitfalls boil down to these four points:

Stick to the VS2022 + oneAPI 2024.2 combination (newer is not necessarily better)
Avoid cloud-synced folders and build in a short local path
On environments whose system code page is not UTF-8 (such as Japanese Windows), set CL=/utf-8 is essential
Write the log to a file (to avoid console stalls and to be able to trace the cause)

Computational Sediment Hydraulics for Fun Learning

Tuesday, 22 September 2026

Building the Delft3D 4 Suite 4.07 Solver on Windows (as of September 2026)