Working on TYPO3 projects in a mixed OS environment can be challenging—especially when you're on a Windows PC and your projects are originally configured for macOS. Add in a VPN (often required to access private resources), and you’ve got a perfect storm of compatibility headaches. If this sounds familiar, read on—we’ll walk through key setup tips, common pitfalls, and how to fix them.
WSL vs Native Windows for TYPO3
First, the good news: you can run TYPO3 projects either inside Windows Subsystem for Linux (WSL) or natively on Windows.
When connected to a VPN, WSL can lose access to certain network routes that the host (Windows) still sees. If your TYPO3 project needs to reach private or internal services over VPN, you may need to run DDEV or other tooling outside WSL to ensure proper access.
Disable IPv6
In some cases it may help to disable IPv6 in your network adapter (just uncheck the box in the settings). You will need to reboot for the changes to take effect.
While this trick initially worked for me, it stopped working after a while, so I decided to work outside the WSL.
If your networking skills are good enough you can certainly route WSL traffic through the VPN, but I feared it's too much of an headache to get this working
Common Issues and Their Fixes
Here’s a rundown of problems you’re likely to encounter—and how to resolve them.
1. Symlink Errors in Git
TYPO3 uses symbolic links, and Windows has a habit of tripping over them—especially if Git isn’t set up correctly. If you see plaintext files with a path inside instead of folders or real files, then git probably has symlinks deactivated.
Fix it by enabling symlink support in Git:
git config --local core.symlinks true
git reset --hard HEADAlso ensure your shell has the necessary permissions. Running Git Bash or a terminal as Administrator may be required.
2. Line Ending Conflicts (CRLF vs LF)
Projects set up on macOS typically use LF (Line Feed) endings. On Windows, Git may default to converting these to CRLF (Carriage Return + Line Feed), causing inconsistent behavior or even broken code in certain environments.
To enforce consistent LF line endings, run:
git config --local core.autocrlf input
git add --renormalize .
git reset --hard HEADTo check for files that still use CRLF line endings:
git ls-files | Where-Object {
Select-String "`r`n" -Path $_ -Quiet
}This will list any remaining CRLF-formatted files so you can review and normalize them.
3. Mutagen doesn't sync
If you're using DDEV and Mutagen for file syncing, ddev start sometimes gets stuck at the mutagen sync step, but you can simply reset it and it will work just fine again.
ddev mutagen reset
This will reset the sync process and typically resolves lockups or stale file issues.
4. NPM vs Yarn
Whether you use yarn or npm depends on whether you already have a lockfile. In case you see a yarn.lock you should use yarn over npm. I also had issues with npm install running into gyp errors inside the docker container which is odd as yarn install works just fine. So in case npm yields errors, it's worth a try to use yarn:
ddev yarn install
To ensure consistent behaviour, make sure all team members use the same package manager.
Final Thoughts
Working on TYPO3 projects in a cross-platform setup can be challenging. But with the right commands, running a project is just as straightforward as on Unix
Quick Recap of Useful Commands:
# Enable Git symlinks
git config --local core.symlinks true
git reset --hard HEAD
# Fix and enforce LF line endings
git config --local core.autocrlf input
git add --renormalize .
git reset --hard HEAD
# List CRLF-formatted files
git ls-files | xargs file | grep CRLF
# Reset DDEV Mutagen
ddev mutagen reset
# Use Yarn in container to avoid NPM issues
ddev yarn installSave this list, bookmark it, or drop it in a project README—it’ll save you (or your teammates) time down the road.