PyOS

Build your own operating system in Python -- then play with it.

Ever wondered what happens when you open a program, save a file, or connect to the internet? PyOS is a complete operating system simulator that lets you see every piece -- processes, memory, filesystems, networking -- and poke at them from a real shell. Built with test-driven development and written for learners.

What Does It Look Like?

  ======================================
            PyOS v0.1.0
     A simulated operating system
  ======================================

  [POST] CPU ... OK
  [POST] Memory ... OK
  [POST] Storage ... OK
  [BOOT] Loading kernel image v0.1.0 ... OK
  [OK] Logger
  [OK] Memory manager (256 frames)
  [OK] Slab allocator
  [OK] File system (journaled)
  [OK] Scheduler (FCFS)
  [OK] Init process (PID 1)

Kernel running. Type 'help' for commands, 'exit' to quit.

root@pyos $ ps
PID  State    Name
1    READY    init

root@pyos $ fork 1
Forked process 1 → child PID 2 (init)

root@pyos $ pstree
init (PID 1)
  └── init (PID 2)

root@pyos $ learn
Available tutorials:
  processes  — What is a process and how do they work?
  memory     — How does the OS manage memory?
  filesystem — How are files stored and organised?
  shell      — What is a shell and why do we need one?
  scheduling — How does the CPU decide what to run next?
Type 'learn <topic>' to start a tutorial.

Features

• Six CPU schedulers -- FCFS, Round Robin, Priority, Aging, MLFQ, and CFS with multi-core support
• Virtual memory -- page tables, address translation, swap (FIFO/LRU/Clock), slab allocator, and mmap
• Journaled filesystem -- inodes, directories, hard/soft links, file descriptors, /proc, and crash recovery
• Full network stack -- sockets, DNS, HTTP, and TCP with three-way handshake, flow control, and congestion control
• Shell scripting -- pipes, variables, conditionals, job control, tab completion, and 80+ built-in commands
• Interactive tutorials -- guided lessons that teach OS concepts hands-on using real system calls

Install

pip install pyos-learn
pyos

Want the browser-based terminal too?

pip install pyos-learn[web]
pyos-web

Learn the Concepts

Each guide explains one part of the OS with real-world analogies and simple language.

Development

git clone https://github.com/robcox2910/py-os.git
cd py-os
uv sync --all-extras
uv run pytest

See CONTRIBUTING.md for coding standards and PR workflow.

Releasing

Other projects in the series (PyStack) use a pinned release of this one, not whatever is on main. To publish a change for them:

1. Merge the change to main.
2. Tag it: git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z. A change to the public API bumps the minor version (v0.1.0 → v0.2.0); anything else bumps the patch (v0.1.0 → v0.1.1).
3. In each project that uses it, edit the tag in [tool.uv.sources], run uv lock --upgrade-package <name>, and open a pull request so CI checks the pair together.

Related Projects

This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the series home for the full story.

Links

• Documentation
• Shell Reference -- all 80+ commands by category
• Architecture -- technical overview of every module
• Visual Guide -- architecture diagrams

Documentation

Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/py-os/