nuta/operating-system-in-1000-lines: a C OS tutorial you build and boot

What problem the 1,000-line constraint actually solves

Most operating system courses hand you a large, partially written kernel and ask you to fill in gaps. You spend the semester reading code you did not write, and the parts you do write are hard to isolate from the parts you did not. This project inverts that. The constraint is size: the whole kernel fits in roughly a thousand lines of C, so a reader can hold the entire boot path, trap handler and scheduler in their head at once.

The audience is specific. It suits a programmer who already writes C and wants to understand what happens between power-on and a user program printing a character. It does not suit someone looking for a kernel to embed in a product, and it does not suit a beginner who has never seen a linker script or an assembly entry point. The book is published at 1000os.seiya.me in English, Japanese, Simplified Chinese, Korean and Traditional Chinese, with the translations credited to individual contributors in the README.

How the reference implementation is laid out

The top-level file list is the architecture. kernel.c and kernel.h hold the kernel itself. common.c and common.h hold code shared between the kernel and user programs, which is why the same helpers can appear on both sides of the privilege boundary. user.c and user.h are the user-space side, and shell.c is a program that runs there. Two linker scripts split the memory layout: kernel.ld for the kernel image and user.ld for user programs. The disk/ directory holds the disk image contents, and run.sh is the entry point that builds and launches everything.

That split is the pedagogical point. A trap from user code into the kernel crosses a boundary that is visible in the file names rather than buried in a framework. The README describes the repository as containing the website source and a reference implementation, and the website/ directory is the book itself. The epub/ directory and make-epub.sh exist to build the EPUB release, which the release list dates to 2025-01-25 for the English edition.

Installing and booting the reference implementation

The README does not contain install steps. It points to the book site, and the repository gives you run.sh as the script that drives the build and the emulator. Read that script before running it, because it is where the QEMU invocation and the compiler flags live. A typical session starts by cloning the repository and invoking the script from the repository root:

git clone https://github.com/nuta/operating-system-in-1000-lines.git
cd operating-system-in-1000-lines
./run.sh

What you should see depends on what run.sh passes to the emulator: the kernel image built from kernel.c and linked with kernel.ld, then user programs built against user.ld. If the script fails immediately, the cause is almost always a missing cross-compiler or a QEMU binary that does not match the target the script expects. Neither the README nor the file list states which target that is, so treat the first line of run.sh as the authoritative answer for your machine.

The build output is not a distributable image. It is a set of objects and a disk directory assembled for the emulator, which is the right shape for a tutorial and the wrong shape for anything you would flash to hardware.

Where the thousand-line scope stops being enough

The README is explicit that the book covers only the basics of an operating system, and it frames the extensions as reader projects rather than shipped features. The two examples it links are a shutdown command and file creation with reads and writes by arbitrary name, both contributed as pull requests by other people. That is a fair signal of what is missing from the core: a filesystem with named files is not part of the baseline, and neither is a clean shutdown path.

There is no networking, no driver model, no memory protection story beyond what a minimal trap handler provides, and no package management. If your goal is to run existing software, this is the wrong tool by construction. If your goal is to understand the minimum viable kernel, the missing pieces are the curriculum. The risk is a reader who finishes the book and assumes the reference implementation is a foundation to grow into a general-purpose system. It is a foundation to grow into a better learning project.

How it compares to writing a kernel from a blank file

The alternative most readers weigh is starting from nothing with the architecture manual open. That path gives you total control over every decision and no guardrails. You will spend your first weeks on toolchain, linker scripts and boot assembly before you see a single character on screen, and you will debug problems that have nothing to do with the concepts you wanted to learn.

This project takes the opposite position: the scaffolding is provided, the scope is capped, and the interesting parts (traps, context switching, user mode) are the parts you read closely. The trade is that you inherit someone else's layout and build script, and the constraint that keeps the code readable also keeps it minimal. A reader who wants to design their own memory layout will find the provided linker scripts more of an obstacle than a help. A reader who wants to see a working trap handler today will find them a shortcut.

Maintenance, licensing and the cost of following along

The repository is not archived, and the last push was on 2026-07-16, so it is being touched. The only release listed is the English EPUB from 2025-01-25, which means the packaged book and the repository code can drift apart; treat the repository as the current source and the EPUB as a snapshot.

Upgrade cost is low in the usual sense, because there are no dependencies to bump. The cost is in the toolchain: a cross-compiler and an emulator that match run.sh. When that script changes, your local setup may need to change with it, and the README does not document a rollback procedure for a working setup. The licence is recorded as NOASSERTION, and there is a LICENCE.md file at the top level. Since the licence identifier is not machine-readable here, read LICENCE.md directly before you reuse any code, and note that the translations are credited to separate contributors, which can matter if you redistribute the book text rather than the code.

Editorial conclusion

Adopt this if you want a guided, small-surface kernel to read and extend, and you are comfortable with C, linker scripts and an emulator. Do not adopt it as a base for a production or general-purpose OS, and do not expect a package manager, networking stack or driver model. Before you start, confirm which QEMU target your toolchain supports and read run.sh to see what the build actually invokes, because the README does not document the toolchain requirements or a rollback path.

Frequently asked questions

Official sources

1. Issues
2. nuta/operating-system-in-1000-lines on GitHub
3. Project website
4. README
5. Releases