WoeUSB Docker

A Docker containerized version of WoeUSB - A Microsoft Windows® USB installation media preparer for GNU+Linux.

📋 Table of Contents

• Features
• Prerequisites
• Quick Start
• Usage
• Important Notes
• Troubleshooting
• Technical Notes
• License

✨ Features

• Docker containerized - No need to install dependencies on your host system
• All dependencies included - Required and optional dependencies pre-installed
• Easy to use - Simple docker-compose setup
• Portable - Works on any Linux system with Docker installed
• Isolated environment - Keeps your host system clean

📦 Prerequisites

• Docker Engine 20.10 or higher
• Docker Compose V2 (or docker-compose 1.29+)
• A Windows ISO file
• A USB drive (will be erased)
• Root/sudo privileges (required for USB operations)

🚀 Quick Start

1. Clone or Download This Repository

cd /path/to/docker-woeusb

⚠️ Important: WoeUSB requires loop devices and must be run as root inside the container. The setup automatically creates /dev/loop0 through /dev/loop7 devices when the container starts.

2. Create Required Directories

mkdir -p isos output

3. Place Your Windows ISO

Copy your Windows installation ISO file to the isos/ directory:

cp /path/to/your/windows.iso isos/

4. Identify Your USB Device

⚠️ WARNING: The target device will be completely erased!

Find your USB device:

lsblk
# or
sudo fdisk -l

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

5. Update docker-compose.yml

Edit docker-compose.yml and uncomment/add your USB device under the devices section:

devices:
  - /dev/sdb:/dev/sdb  # Replace sdb with your actual USB device

6. Build the Docker Image

docker-compose build

7. Verify Setup (Optional but Recommended)

Run the verification script to ensure everything is configured correctly:

./verify-setup.sh

This will check:

• Docker installation
• Required files and directories
• Loop device creation
• Container functionality

8. Run the Container

docker-compose run --rm woeusb

🔧 Usage

Once inside the container, you can use WoeUSB with the following syntax:

Basic Syntax

sudo woeusb [options] <source> <target>

Method 1: Device Mode (Recommended)

Creates a bootable USB drive by formatting the entire device:

sudo woeusb --device /isos/windows.iso /dev/sdb

Parameters:

• /isos/windows.iso - Path to your Windows ISO file
• /dev/sdb - Your USB device (replace with actual device)

Method 2: Partition Mode

Creates bootable media on an existing partition:

sudo woeusb --partition /isos/windows.iso /dev/sdb1

Common Options

# Show help
woeusb --help

# Use FAT32 filesystem (default)
sudo woeusb --device --target-filesystem FAT /isos/windows.iso /dev/sdb

# Use NTFS filesystem (for files > 4GB)
sudo woeusb --device --target-filesystem NTFS /isos/windows.iso /dev/sdb

# Verbose output
sudo woeusb --device -v /isos/windows.iso /dev/sdb

Example Session

# Start the container
docker-compose run --rm woeusb

# Inside the container, list available ISOs
ls -lh /isos

# Check USB device
lsblk

# Verify loop devices exist (created automatically)
ls -l /dev/loop*

# Create bootable USB (must use sudo)
sudo woeusb --device /isos/Windows10.iso /dev/sdb

# Exit container when done
exit

⚠️ Important Notes

Security Considerations

• The container runs in privileged mode to access USB devices
• The container has full access to specified devices
• Always double-check the target device before proceeding
• Data on the target USB drive will be completely erased

Device Access

• You must specify USB devices in docker-compose.yml before starting
• Devices must be added to the devices section under the service
• You can add multiple devices if needed:

devices:
  - /dev/sdb:/dev/sdb
  - /dev/sdc:/dev/sdc

Filesystem Types

• FAT32: Maximum file size is 4GB

  • Use for most Windows installation media
  • Best compatibility

• NTFS: No file size limit

  • Use when install.wim is larger than 4GB
  • Requires UEFI:NTFS bootloader (automatically downloaded)

Supported Windows Versions

• Windows Vista and later
• Windows 7, 8, 8.1, 10, 11
• Windows PE
• Any language or edition variant

🐛 Troubleshooting

Container Can't Access USB Device

Solution: Make sure the device is added to docker-compose.yml and you're running with --privileged:

docker-compose run --rm woeusb

Loop Device Not Found

Solution: Loop devices are created automatically by the entrypoint script. If you still encounter issues, manually create them:

# Inside the container as root
sudo mknod /dev/loop0 b 7 0
sudo mknod /dev/loop1 b 7 1
# ... up to loop7

Or create all at once:

for i in {0..7}; do sudo mknod /dev/loop$i b 7 $i 2>/dev/null || true; done

"Device is busy" Error

Solution: Unmount the USB device first:

# On host system
sudo umount /dev/sdb*

Permission Denied

Solution: Ensure you're using sudo inside the container:

sudo woeusb --device /isos/windows.iso /dev/sdb

ISO File Not Found

Solution: Make sure the ISO is in the isos/ directory and properly mounted:

# Check mounted volumes
ls -lh /isos

Split WIM File Error

If you see errors about install.wim being too large for FAT32:

Solution 1: Use NTFS filesystem:

sudo woeusb --device --target-filesystem NTFS /isos/windows.iso /dev/sdb

Solution 2: WoeUSB will automatically split the WIM file if wimtools is installed (included in this Docker image).

Out of Space

Solution: Ensure your USB drive has enough capacity:

• Windows 7: Minimum 4GB
• Windows 8/10/11: Minimum 8GB recommended

📁 Directory Structure

docker-woeusb/
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker Compose configuration
├── README.md              # This file
├── QUICKSTART.md          # Quick start guide
├── TECHNICAL_NOTES.md     # Detailed technical documentation
├── woeusb-docker.sh       # Interactive helper script
├── verify-setup.sh        # Setup verification script
├── WoeUSB/                # WoeUSB source files
│   ├── sbin/
│   │   └── woeusb        # Main WoeUSB script
│   └── share/            # Shared resources
├── isos/                 # Place your Windows ISO files here
└── output/               # Optional output directory

🔍 Advanced Usage

Running Without Docker Compose

# Build image
docker build -t woeusb:latest .

# Run container
docker run -it --rm --privileged \
  -v $(pwd)/isos:/isos:ro \
  -v $(pwd)/output:/output \
  --device=/dev/sdb:/dev/sdb \
  woeusb:latest

Environment Variables

You can set environment variables in docker-compose.yml:

environment:
  - RUFUS_UEFI_NTFS_VERSION=b30e3b387a3ca7a5e2fddebcc2c8f9538a89b868
  - DD_BLOCK_SIZE=4194304

Accessing Container Shell

# Start an interactive shell
docker-compose run --rm woeusb /bin/bash

# Or using docker directly
docker run -it --rm --privileged woeusb:latest /bin/bash

📝 License

This Docker configuration is provided as-is for use with WoeUSB.

WoeUSB itself is free software licensed under the GNU General Public License version 3 (or any later version). See the WoeUSB project for complete license information.

🙏 Credits

• WoeUSB Project: https://github.com/WoeUSB/WoeUSB
• Original WinUSB by Colin GILLE
• Maintained by the WoeUSB community
• Docker configuration by the community

🔗 Useful Links

• WoeUSB GitHub Repository
• WoeUSB Wiki
• Report Issues

---

Note: Always verify your USB device path before running WoeUSB to avoid data loss on the wrong device!