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 directoryThis 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\Delft3DDo 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\Delft3DPython 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\activateRun 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 externalexternal 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 listThe 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-8On 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 #endifThe 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-8is essential - Write the log to a file (to avoid console stalls and to be able to trace the cause)
