Solutions for common Windows-specific issues with ModelForge.

Problem: "Unsloth is not installed" or import errors on native Windows

Cause: Unsloth requires Linux-specific libraries and compilation

Solutions:

1. Use WSL 2 (Recommended): WSL Installation Guide
2. Use Docker: Docker Installation Guide
3. Use HuggingFace Provider: Works perfectly on native Windows

The CLI wizard (modelforge cli) works on native Windows — no WSL needed. Only the Unsloth provider requires WSL or Docker.

pip install modelforge-finetuning[cli]
modelforge cli

Problem: nvidia-smi works in Windows but not in WSL

Solutions:

1. Update Windows to latest version (Build 21H2 or later)
2. Update NVIDIA drivers to 525.60 or newer
3. Ensure WSL 2 is installed:

   wsl --status

4. Restart WSL:

   wsl --shutdown

   Then reopen Ubuntu

Problem: nvcc: command not found in WSL

Solution: Install CUDA Toolkit in WSL (not Windows):

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install -y cuda-toolkit-12-6

Problem: Docker container can't access GPU

Solutions:

1. Ensure WSL 2 backend is enabled in Docker Desktop
2. Install nvidia-container-toolkit in WSL:

   distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
   curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
   curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
   sudo apt-get update
   sudo apt-get install -y nvidia-container-toolkit

3. Restart Docker Desktop

Problem: Dockerfile build errors

Solution: Ensure WSL integration is enabled:

1. Docker Desktop → Settings → Resources → WSL Integration
2. Enable integration for Ubuntu distribution
3. Restart Docker Desktop

Problem: Cannot create files/directories

Solutions:

In WSL:

sudo chown -R $USER:$USER ~/ModelForge

In Windows: Run PowerShell as Administrator

Problem: modelforge command not found

Solutions:

In PowerShell:

# Add to PATH
$env:PATH += ";$env:USERPROFILE\AppData\Local\Programs\Python\Python311\Scripts"

In WSL:

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Problem: Token not found despite setting

Solutions:

PowerShell (Session):

$env:HUGGINGFACE_TOKEN="your_token"

PowerShell (Permanent):

[System.Environment]::SetEnvironmentVariable('HUGGINGFACE_TOKEN', 'your_token', 'User')

CMD:

setx HUGGINGFACE_TOKEN "your_token"

Restart terminal after setting permanent variables.

Solutions:

1. Use WSL instead of native Windows (better I/O performance)
2. Install dataset on NVMe SSD
3. Disable Windows Defender for project folder
4. Close unnecessary Windows applications

Solutions:

1. Limit Windows background processes
2. Disable Windows Search indexing for project folder
3. Use WSL for better resource management

Problem: JSONL files have wrong line endings

Solution: Convert CRLF to LF:

(Get-Content dataset.jsonl) | Set-Content dataset.jsonl

Problem: Paths with backslashes don't work

Solution: Use forward slashes or raw strings:

# Good
path = "C:/Users/username/dataset.jsonl"
path = r"C:\Users\username\dataset.jsonl"

# Bad
path = "C:\Users\username\dataset.jsonl"  # Escaping issues

Problem: "File path too long" errors

Solution: Enable long paths in Windows:

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Restart computer.

Solution: Add exception:

1. Windows Security → Virus & threat protection → Manage settings
2. Add exclusion for ModelForge folder

Solution: Add firewall rule:

New-NetFirewallRule -DisplayName "ModelForge" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action Allow

Solution: Install Visual C++ Redistributable: Download from Microsoft

Solutions:

1. Install Visual C++ Redistributable
2. Update Windows
3. Reinstall Python

Solutions:

1. Run PowerShell as Administrator
2. Check folder permissions
3. Disable antivirus temporarily

Solution: Configure WSL memory limit in .wslconfig:

Create C:\Users\<username>\.wslconfig:

[wsl2]
memory=16GB
processors=8
swap=8GB

Restart WSL:

wsl --shutdown

Access WSL from Windows:

\\wsl$\Ubuntu-22.04\home\username\

Access Windows from WSL:

/mnt/c/Users/username/

• General Troubleshooting
• FAQ
• Windows Installation Guide
• GitHub Issues

Windows-specific issue not listed? Ask in GitHub Discussions.