docker-woeusb/QUICKSTART.md

WoeUSB Docker - Quick Start Guide

🚀 Fastest Way to Get Started

⚠️ Important: WoeUSB requires root privileges and loop devices. The container automatically creates loop devices (/dev/loop0-7) on startup.

Step 1: Prepare Everything

# Create directories
mkdir -p isos output

# Copy your Windows ISO to the isos folder
cp /path/to/your/Windows.iso isos/

Step 2: Build the Docker Image

docker-compose build

Step 3: Find Your USB Device

lsblk

Look for your USB drive (e.g., /dev/sdb). Make sure you identify the correct device!

Step 4: Use the Helper Script (Easiest Method)

Interactive Mode (Recommended for Beginners)

./woeusb-docker.sh

Follow the menu to:

1. List ISO files
2. See USB devices
3. Build the image
4. Create bootable USB

Command Line Mode (For Advanced Users)

# List available ISOs
./woeusb-docker.sh list-isos

# List USB devices
./woeusb-docker.sh list-devices

# Create bootable USB with FAT32
./woeusb-docker.sh create isos/Windows10.iso /dev/sdb FAT

# Create bootable USB with NTFS (for large files)
./woeusb-docker.sh create isos/Windows11.iso /dev/sdb NTFS

Step 5: Manual Method (Alternative)

If you prefer not to use the helper script:

# Run interactively
docker-compose run --rm woeusb

# Inside the container
sudo woeusb --device /isos/YourWindows.iso /dev/sdb

⚡ One-Liner Examples

FAT32 (Most Compatible)

docker run -it --rm --privileged \
  -v $(pwd)/isos:/isos:ro \
  --device=/dev/sdb:/dev/sdb \
  woeusb:latest \
  sudo woeusb --device /isos/Windows10.iso /dev/sdb

NTFS (For Files > 4GB)

docker run -it --rm --privileged \
  -v $(pwd)/isos:/isos:ro \
  --device=/dev/sdb:/dev/sdb \
  woeusb:latest \
  sudo woeusb --device --target-filesystem NTFS /isos/Windows11.iso /dev/sdb

🆘 Common Issues

"Device busy" error

# Unmount the USB first
sudo umount /dev/sdb*

"Permission denied"

# Make sure to use sudo inside the container
sudo woeusb --device /isos/windows.iso /dev/sdb

"Loop device not found"

# Loop devices are created automatically, but if needed:
sudo mknod /dev/loop0 b 7 0
# Or create all loop devices:
for i in {0..7}; do sudo mknod /dev/loop$i b 7 $i 2>/dev/null || true; done

Can't find USB device in container

Edit docker-compose.yml and add your device:

devices:
  - /dev/sdb:/dev/sdb  # Your USB device

⏱️ How Long Does It Take?

• USB 2.0: 20-40 minutes
• USB 3.0: 10-20 minutes
• USB 3.1/3.2: 5-15 minutes

Time varies based on ISO size and USB speed.

📝 Notes

• Always verify your USB device path before starting
• The USB drive will be completely erased
• Keep the ISO file in the isos/ directory
• Use NTFS if your install.wim file is larger than 4GB

🎯 Full Documentation

See README.md for complete documentation.

---

Need Help? Check the Troubleshooting section in the full README.