floppinux

# FLOPPINUX - An Embedded 🐧Linux on a Single 💾Floppy
## 2026 Edition (v0.3.1.x64mod)

- v0.3.1.x64mod - **January 29, 2026**
- v0.3.1 - **December 21, 2025**
- v0.3.0 - **October 19, 2025**

---

> FLOPPINUX was released in 2021. After four years people find it helpful. Because of that I decided to revisit FLOPPINUX in 2025 and make updated tutorial. This brings bunch of updates like latest kernel and persistent storage.

## Table of Contents

- [Main Project Goals](#main-project-goals)
- [Linux Kernel](#linux-kernel)
- [64-bit Base OS](#64-bit-base-os)
- [Working Directory](#working-directory)
- [System Requirements](#system-requirements)
- [Kernel](#kernel)
- [Toolset](#toolset)
- [Filesystem](#filesystem)
- [Boot Image](#boot-image)
- [Floppy Disk](#floppy-disk)
- [Summary](#summary)
- [Download](#download)

## Main Project Goals

Think of this as Linux From Scratch but for making single floppy distribution.

> It is meant to be a full workshop (tutorial) that you can follow easily and modify it to your needs. It is a learning exercise. Some base Linux knowledge is needed.

The final distribution is very simple and consists only of minimum of tools and hardware support. As a user you will be able to boot any PC with a floppy drive *(either physical or virtual, preferably 2.88MB one according to this instruction aimed for coreboot+SeaBIOS)* to a Linux terminal, edit files, and create simple scripts. There is ??? KB of space left for your newly created files.

### Core features:

- Fully working distribution booting from the single floppy
- Latest* Linux kernel
- Supporting all 32-bit x86 CPUs since Intel 486DX - **HOWEVER, IT WAS LIKE THAT ONLY BEFORE I SWITCHED THIS INSTRUCTION TO X86_64**
- Have a working text editor (Vi) and basic file manipulation commands (move, rename, delete, etc.)
- Support for simple scripting
- Persistent storage on the floppy to actualy save files (264KB)
- Works on real hardware and emulation

### Minimum Hardware Requirements:

- Intel 486DX 33MHz - **HOWEVER, IT WAS LIKE THAT ONLY BEFORE I SWITCHED THIS INSTRUCTION TO X86_64**
- 20MB RAM
- Internal floppy disk - **OR A VIRTUAL FLOPPY DISK IMAGE, THAT COULD BE AS LARGE AS 2.88 MB, TO USE IT AS A PART OF COREBOOT+SEABIOS ROM**

## Linux Kernel

The Linux kernel drops i486 support in 6.15 (released May 2025), so **6.14.11** (released March 2025) is the latest version with full compatibility. **HOWEVER, SINCE I SWITCHED THIS INSTRUCTION TO X86_64, WE COULD TAKE THE LATEST STABLE 6.18.7**

## 64-bit Base OS

This time I will do everything on **Artix** Linux (Arch without SystemD). It is 64-bit operating system based on Arch Linux. Instructions should work on all POSIX systems. Only difference is getting needed packages.

## Working Directory

Create directory where you will keep all the files.

```bash
mkdir ~/my-floppy-distro/
BASE=~/my-floppy-distro/
cd $BASE
```

## Host OS Requirements

> You need supporting software to build things. This exact list may vary depending on the system you have.

Install needed software/libs. On Artix:

```bash
sudo pacman -S ncurses bc flex bison syslinux cpio
```

Cross-compiler:

```bash
wget https://musl.cc/x86_64-linux-musl-cross.tgz
tar -xvf ./x86_64-linux-musl-cross.tgz
rm ./x86_64-linux-musl-cross.tgz
```

### Emulation

> 86Box is also good but slower. Bochs is the best but for debugging, not needed here.

For emulation I will be using qemu.

```bash
sudo pacman -S qemu-full
```

**NOTE: keep in mind that the nested virtualization of x86_64 may not work, especially if you are trying to use QEMU under VirtualBox**

## Kernel

Get the sources for the latest compatible **kernel 6.18.7**:

```bash
git clone --depth=1 --branch v6.18.7 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
cd ./linux/
```

Now, that you have them in **linux/** directory lets configure and build our custom kernel. First create tiniest base configuration:

```bash
make ARCH=x86_64 tinyconfig
```

> This is a bootstrap with absolute minimum features. Just enough to boot the system. We want a little bit more.

Add additonal config settings on top of it:

```bash
make ARCH=x86_64 menuconfig
```
Important: Do not uncheck anything in options unless specified so. Some of those options are important. You can uncheck but on your own risk.

From menus choose those options:

- General Setup
  - Configure standard kernel features (expert users)
    - Enable support for printk: CONFIG_PRINTK
  - Kernel compression mode: CONFIG_KERNEL_XZ -> CONFIG_KERNEL_LZMA
  **ACTUALLY NO, CONFIG_KERNEL_XZ IS SLIGHTLY BETTER: 2171904 vs 2274304 for the extended build**
  - Initial RAM filesystem and RAM disk (initramfs/initrd)
    - Support initial ramdisk/ramfs compressed using LZMA CONFIG_RD_LZMA and **uncheck everything else**
- Enable the block layer: CONFIG_BLOCK
- Executable file formats
  - Kernel support for ELF binaries: CONFIG_BINFMT_ELF
  - Kernel support for scripts starting with #!: CONFIG_BINFMT_SCRIPT
- Bus options:
  - ISA-style DMA support: ISA_DMA_API (for ARCH_MAY_HAVE_PC_FDC for CONFIG_BLK_DEV_FD)
- Device Drivers:
  - Block devices
    - Normal floppydisk support: CONFIG_BLK_DEV_FD (depends on ISA_DMA_API for ARCH_MAY_HAVE_PC_FDC)
    - RAM block device support: CONFIG_BLK_DEV_RAM
      - Default number of RAM disk: 1 (CONFIG_BLK_DEV_RAM_COUNT)
  - Character devices
    - Enable TTY: CONFIG_TTY
- File systems
  - DOS/FAT/EXFAT/NT Filesystems
    - MSDOS fs support: CONFIG_MSDOS_FS
  - Pseudo filesystems
    - /proc file system support: CONFIG_PROC_FS
    - sysfs file system support: CONFIG_SYSFS
  - Native language support
    - Codepage 437: CONFIG_NLS_CODEPAGE_437
- Library routines
  - LZMA decompression: CONFIG_DECOMPRESS_LZMA) (selected by RD_LZMA && BLK_DEV_INITRD)

Exit configuration (yes, save settings to .config).

Time for compiling!

### Compile Kernel

```bash
make ARCH=x86_64 bzImage
```

This will take a while depending on the speed of your CPU. In the end the kernel will be created in **arch/x86/boot/** as **bzImage** file.

Copy kernel to our **main directory** and **go back to it**:

```bash
rm -f ./../bzImage
cp ./arch/x86_64/boot/bzImage ./../
cd ./../
```

## Toolset

Without tools kernel will just boot and you will not be able to do anything. One of the most popular lightweight tools is BusyBox. It replaces the standard GNU utilities with way smaller but still functional alternatives, perfect for embedded needs.

Get the **1.37.0** version from busybox.net or Github mirror. Download the file, extract it, and change directory:

> Remember to be in the working directory.

```bash
git clone --branch 1_37_stable https://git.busybox.net/busybox.git
cd ./busybox/
```

As with kernel you need to create starting configuration:

```bash
make ARCH=x86_64 allnoconfig
```

> You may skip this following fix if you are building on Debian/Fedora

Fix for **Arch Linux based distributions**:

```bash
sed -i 's/main() {}/int main() {}/' ./scripts/kconfig/lxdialog/check-lxdialog.sh
```

> Now the fun part. You need to **choose what tools you want**. Each menu entry will show how much more KB will be taken if you choose it. So choose it wisely :) For the first time use my selection.

Run the configurator:

```bash
make ARCH=x86_64 menuconfig
```

Choose the following options. Remember to **do not uncheck** anything if not stated here.

- Settings
  - Support files > 2 GB: CONFIG_LFS
  - Build static binary (no shared libs): CONFIG_STATIC
- Coreutils
  - cat: CONFIG_CAT
  - cp: CONFIG_CP
  - df: CONFIG_DF
  - echo: CONFIG_ECHO
  - ln: CONFIG_LN
  - ls: CONFIG_LS
  - mkdir: CONFIG_MKDIR
  - mv: CONFIG_MV
  - rm: CONFIG_RM
  - sync: CONFIG_SYNC
  - test: CONFIG_TEST
    - test as [: CONFIG_TEST1
    - test as [[: CONFIG_TEST2
- Console Utilities
  - clear: CONFIG_CLEAR
- Editors
  - vi: CONFIG_VI
- Init Utilities
  - init: CONFIG_INIT
    - **uncheck** everything else (inside init: keep [*] only on init in this page)
- Linux System Utilities
  - mdev: CONFIG_MDEV
  - mount: CONFIG_MOUNT
    - Support lots of -o flags: CONFIG_FEATURE_MOUNT_FLAGS
    - **uncheck** everything else
  - setsid: CONFIG_SETSID
  - umount: CONFIG_UMOUNT
- Miscellaneous Utilities
  - **uncheck** readahead: CONFIG_READAHEAD
- Shells
  - Choose alias as (ash): CONFIG_SH_IS_ASH
  - ash: CONFIG_ASH
    - Optimize for size instead of speed: ASH_OPTIMIZE_FOR_SIZE
    - Alias support: ASH_ALIAS
  - cttyhack: CONFIG_CTTYHACK
  <!--- Help support-->

Now exit with save config.

### Cross Compiler Setup

> Our target system needs to be 64-bit MUSL. To compile it on 64-bit no-MUSL system we need a cross compiler. You can setup this by hand in the menuconfig or just copy and paste those four lines.

Setup paths:

```bash
BASE=~/my-floppy-distro/
sed -i "s|.*CONFIG_CROSS_COMPILER_PREFIX.*|CONFIG_CROSS_COMPILER_PREFIX=\"${BASE}/x86_64-linux-musl-cross/bin/x86_64-linux-musl-\"|" ./.config

sed -i "s|.*CONFIG_SYSROOT.*|CONFIG_SYSROOT=\"${BASE}/x86_64-linux-musl-cross\"|" ./.config

sed -i "s|.*CONFIG_EXTRA_CFLAGS.*|CONFIG_EXTRA_CFLAGS=\"-I$BASE/x86_64-linux-musl-cross/include\"|" ./.config

sed -i "s|.*CONFIG_EXTRA_LDFLAGS.*|CONFIG_EXTRA_LDFLAGS=\"-L$BASE/x86_64-linux-musl-cross/lib\"|" ./.config
```

### Compile BusyBox

Build tools and create base filesystem ("install"). It will ask for options, just **press enter** for default for all of them.

```bash
BASE=~/my-floppy-distro/
make ARCH=x86_64
rm -rf ./_install/
make ARCH=x86_64 install
```

This will create a filesystem with all the files at **_install/**. Move it to our main directory. I like to rename it to.

Lastly to to that new directory.

```bash
sudo rm -rf ./../filesystem
cp -r ./_install/ ./../filesystem
cd ./../filesystem
```

## Filesystem

You got kernel and basic tools but the system still needs some additional directory structure.

> This created minimum viable directory structure for satisfying the basic requirements of a Linux system.

> Remember to be in the filesystem/ directory.

```bash
mkdir -pv {dev,proc,etc/init.d,sys,tmp,home}
sudo mknod ./dev/console c 5 1
sudo mknod ./dev/null c 1 3
```

Next step is to add minimum configuration files. First one is a welcome message that will be shown after booting.

> Here is the first real opportunity to go wild and make this your own signature.

```bash
cat >> ./welcome << EOF
Your welcome message or ASCII art.
EOF
```

Or download my welcome file.

```bash
wget https://krzysztofjankowski.com/floppinux/downloads/0.3.1/welcome
```

It looks like that:

```
$ cat ./welcome

                _________________
               /_/ FLOPPINUX  /_/;
              / ' boot disk  ' //
             / '------------' //
            /   .--------.   //
           /   /         /  //
          .___/_________/__//   2880KiB
          '===\_________\=='   3.5"

_______FLOPPINUX_V_0.3.1 __________________________________
_______AN_EMBEDDED_SINGLE_FLOPPY_LINUX_DISTRIBUTION _______
_______BY_KRZYSZTOF_KRYSTIAN_JANKOWSKI ____________________
_______2026.01 ____________________________________________
```

> Back to serious stuff. Inittab tells the system what to do in critical states like starting, exiting and restarting. It points to the initialization script rc that is the first thing that our OS will run before dropping into the shell.

Create an inittab file:

```bash
cat >> ./etc/inittab << EOF
::sysinit:/etc/init.d/rc
::askfirst:/usr/bin/setsid /bin/cttyhack /bin/sh
::respawn:/usr/bin/setsid /bin/cttyhack /bin/sh
::restart:/sbin/init
::ctrlaltdel:/sbin/reboot
::shutdown:/bin/umount -a -r
EOF
```

And the init rc script:

```bash
cat >> ./etc/init.d/rc << EOF
#!/bin/sh
mount -t proc none /proc
mount -t sysfs none /sys
mdev -s
ln -s /proc/mounts /etc/mtab
mkdir -p /mnt /home
mount -t msdos -o rw /dev/fd0 /mnt
mkdir -p /mnt/data
mount --bind /mnt/data /home
clear
cat ./welcome
cd /home/
/usr/bin/setsid /bin/cttyhack /bin/sh
EOF
```

Make the script executable and owner of all files to root:

```bash
chmod +x ./etc/init.d/rc
sudo chown -R root:root ./
```

Compress this directory into one file. Then go back to working directory.

```bash
rm -f ./../rootfs.cpio.lzma
find . | cpio -H newc -o | xz --format=lzma --check=crc32 --lzma1=dict=512KiB,preset=9e > ./../rootfs.cpio.lzma
cd ./../
ls -al ./rootfs.cpio.lzma
```

Create booting configuration.

> Another place to tweak parameters for your variant. Text after SAY is what will be displayed on the screen as first, usualy a name of the OS.

> The tsc=unstable is useful on some (real) computers to get rid of randomly shown warnings about Time Stamp Counter.

> Remember to be in the working directory.

```bash
rm -f ./syslinux.cfg
cat >> ./syslinux.cfg << EOF
DEFAULT floppinux
LABEL floppinux
SAY [ BOOTING FLOPPINUX VERSION 0.3.1 ]
KERNEL bzImage
INITRD rfscpiol.zma
APPEND root=/dev/ram rdinit=/etc/init.d/rc console=tty0 tsc=unstable
EOF
```

Make it executable:

```bash
chmod +x ./syslinux.cfg
```

Create sample file

> To make the system a little bit more user friendly I like to have a sample file that user will be able to read and edit. You can put anything you want in it. A simple help would be also a good idea to include.

```bash
rm -f ./hello.txt
cat >> ./hello.txt << EOF
Hello, FLOPPINUX user!
EOF
```

Filesystem is ready. Final step is to **put this all on a floppy**!

## Boot Image

First we need an empty file in exact size of a floppy disk. Then format and make it bootable.

Create empty floppy image:

```bash
rm -f ./floppinux.img
dd if=/dev/zero of=./floppinux.img bs=1k count=2880
```

Format it and create bootloader:

```bash
mkdosfs -n FLOPPINUX ./floppinux.img
syslinux --install ./floppinux.img
```

Mount it and copy syslinux, kernel, and filesystem onto it:

```bash
sudo mount -o loop ./floppinux.img /mnt
sudo mkdir /mnt/data
sudo cp ./hello.txt /mnt/data/
sudo cp ./bzImage /mnt
sudo cp ./rootfs.cpio.lzma /mnt/rfscpiol.zma
sudo cp ./syslinux.cfg /mnt
df -h
sudo umount /mnt
```

Done!

### Test in emulator

It's good to test before wasting time for the real floppy to burn.

Boot the new OS in qemu:

```bash
qemu-system-x86_64 -fda floppinux.img
```

If it worked that means You have successfully created your own distribution! Congratulations!

The **floppinux.img** image is ready to burn onto a floppy and boot on real hardware!

## Floppy Disk

### <!> Important <!>

Change XXX to floppy drive name in your system. In my case it is **sdb**. Choosing wrongly will **NUKE YOUR PARTITION** and **REMOVE** all of your files! Think twice. Or use some GUI application for that.

```bash
sudo dd if=./floppinux.img of=/dev/XXX bs=512 conv=notrunc,sync,fsync iflag=nocache oflag=direct status=progress
```

After 5 minutes I got freshly burned floppy.

## Debugging

If you need more verbose logging use those syslinux.cfg settings.

```
rm -f ./syslinux.cfg
cat >> ./syslinux.cfg << EOF
DEFAULT floppinux
LABEL floppinux
SAY [ BOOTING FLOPPINUX VERSION 0.3.1 DEBUG ]
KERNEL bzImage
INITRD rfscpiol.zma
APPEND root=/dev/ram rdinit=/etc/init.d/rc console=tty0 ignore_loglevel earlyprintk=tty0 loglevel=8 tsc=unstable
EOF
```

## Summary

- FLOPPINUX: **0.3.1.x64mod** (January 2026)
- Linux Kernel: **6.18.7**
- Busybox: **1.37.0**
- Image size: 2880KiB / 2.88MiB
- Kernel size: 1069KiB (bzImage) - minimal
- Tools: 131KiB (rfscpiol.zma) - minimal
- Free space left (df -h): **1486KiB**

### System Tools

#### File & Directory Manipulation
- ```cat``` - display file contents
- ```cp``` - copy files and directories
- ```mv``` - move/rename files and directories
- ```rm``` - remove files and directories
- ```ls``` - list directory contents
- ```mkdir``` - creates directory

#### System Information & Management
- ```df -h``` - display filesystem disk space usage
- ```sync``` - force write of buffered data to disk - use this after any changes to the floppy filesystem
- ```mount``` - mount filesystems
- ```umount``` - unmount filesystems

#### Text Processing & Output
- ```echo``` - display text output
- ```more``` - page through text output

#### Utilities
- ```clear``` - clear terminal screen
- ```test``` - evaluate conditional expressions

### Applications

- ```vi``` - text editor

## Download

- [FLOPPINUX 0.3.1 Floppy Image 1.44MB](http://krzysztofjankowski.com/floppinux/downloads/0.3.1/floppinux.img)

---

```
                         _________________
                        /_/ FLOPPINUX  /_/;
                       / ' boot disk  ' //
                      / '------------' //
                     /   .--------.   //
                    /   /         /  //
                   .___/_________/__//   2880KiB
                   '===\_________\=='   3.5"


                Now go and make something fun with it!
```

**FLOPPINUX - An Embedded Single Floppy Linux Distribution**
**By Krzysztof Krystian Jankowski**
**2026.01**