Spaces:
Running
Running
File size: 5,100 Bytes
bc9c638 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 | # Windows Notes
Side-Step fully supports Windows with CUDA GPUs. This page documents Windows-specific behavior, workarounds, and configuration details that differ from Linux/macOS.
---
## Installation
The easiest way to install on Windows is the **Easy Installer**:
1. Clone or download Side-Step.
2. Double-click `install_windows.bat` (or run `install_windows.ps1` from PowerShell).
The installer handles everything:
- Installs `uv` (if not already present)
- Installs Python 3.11
- Clones ACE-Step 1.5 alongside Side-Step
- Runs `uv sync` for all dependencies
- Optionally downloads model checkpoints
**Requirements:** Windows 10/11, PowerShell 5.1+, Git, NVIDIA GPU with CUDA drivers.
The installer creates two sibling directories:
```
Parent/
├── Side-Step/ <-- Your training toolkit
└── ACE-Step-1.5/ <-- Model checkpoints + optional vanilla mode
```
### Running from PowerShell
```powershell
cd Side-Step
uv run train.py
```
Both PowerShell and CMD work. The wizard displays Windows-native paths (backslashes) in its prompts.
---
## DataLoader Workers (num_workers = 0)
**On Windows, Side-Step forces `num_workers=0` regardless of what you set.**
This is because Windows uses spawn-based multiprocessing (rather than fork), which breaks PyTorch's DataLoader workers. Attempting to use workers > 0 on Windows causes crashes or hangs.
Side-Step handles this automatically:
- The CLI default is `0` on Windows.
- The wizard warns you and clamps to `0` if you enter a higher value.
- The trainer enforces `0` at runtime even if overridden via CLI.
When `num_workers=0`:
- `prefetch_factor` is forced to `0` (no background prefetching).
- `persistent_workers` is forced to `False`.
**Impact:** Data loading is slightly slower (single-threaded), but training speed is dominated by GPU computation, so the difference is usually negligible.
---
## Multi-GPU Device Selection
On Windows, Lightning Fabric's `devices=[index]` parameter causes `DistributedSampler` to produce 0 batches, which makes training silently "complete" with 0 steps.
Side-Step works around this by using `devices=1` and calling `torch.cuda.set_device(device_idx)` directly. This means multi-GPU selection (e.g., `--device cuda:1`) works correctly on Windows.
---
## Configuration and Preset Paths
Side-Step stores user configuration and presets at Windows-standard locations:
| Item | Path |
| :--- | :--- |
| Settings | `%APPDATA%\sidestep\settings.json` |
| Global presets | `%APPDATA%\sidestep\presets\` |
| Local presets | `.\presets\` (in the Side-Step project directory) |
`%APPDATA%` typically resolves to `C:\Users\<you>\AppData\Roaming`.
Local presets take priority over global presets. See [[Preset Management]] for details.
---
## Log File
Side-Step writes a log file (`sidestep.log`) to the current working directory. On some Windows setups (e.g., running from a read-only directory or a restricted location), the log file may fail to create. In that case, Side-Step falls back to console-only logging with no error.
If you need the log file for troubleshooting, make sure you run Side-Step from a writable directory (e.g., the Side-Step project folder itself).
---
## Preset Name Safety
Preset names are validated against Windows reserved filenames. The following names are rejected:
`CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9`
Characters `/\:*?"<>|` are also stripped from preset names. This validation applies on all platforms, not just Windows, to keep presets portable.
---
## Path Length (MAX_PATH)
Windows has a historical 260-character path length limit (MAX_PATH). Side-Step does not explicitly handle this. If you encounter path-related errors:
- Keep your project close to the drive root (e.g., `C:\ai\Side-Step\` rather than deeply nested directories).
- Avoid very long output directory names.
- Consider enabling long paths in Windows: Settings > System > For Developers > Enable long paths. This requires Windows 10 version 1607 or later.
---
## Summary of Windows-Specific Behavior
| Behavior | What Happens | Why |
| :--- | :--- | :--- |
| `num_workers` clamped to `0` | DataLoader runs single-threaded | Windows spawn-based multiprocessing breaks PyTorch workers |
| `prefetch_factor` forced to `0` | No background batch prefetching | Required when `num_workers=0` |
| `persistent_workers` forced off | Workers not kept alive between epochs | Required when `num_workers=0` |
| Fabric `devices=1` | Uses `torch.cuda.set_device()` instead of device list | `devices=[index]` causes 0-batch bug on Windows |
| Backslash paths in prompts | Path display uses `\` separator | Native Windows path convention |
| Config stored in `%APPDATA%` | Settings and global presets in AppData | Windows standard user config location |
| File explorer uses `explorer` | "Open folder" actions use Windows Explorer | Platform-appropriate file manager |
---
## See Also
- [[Getting Started]] -- Installation and first-run setup
- [[Preset Management]] -- Preset storage and management
- [[VRAM Optimization Guide]] -- GPU memory profiles
|