Building a Functioning Python Interpreter in 1024 Bytes

Most developers look at the Python runtime as a black box. You feed a .py file into python3, CPython parses the source text into an Abstract Syntax Tree (AST), compiles that tree into bytecode, and passes the bytecode to an evaluation loop inside ceval.c. The standard CPython binary easily tops 15 megabytes on disk. Even lightweight embedded runtimes like MicroPython demand around 250 kilobytes of flash memory.

Stripping an execution environment down to 1024 bytes forces you to rethink every layer of language design. You cannot afford an AST node allocator, symbol table hash maps, complex exception frames, or string formatting engines. Much like building an operating system from assembly, working at this scale requires absolute control over system resources.

The goal here is not to replace CPython. The goal is code golf combined with runtime architecture: building a functional, stack-based bytecode virtual machine and scanner that fits inside a single kilobyte of source code while executing real Python-like syntax.

Defining the 1024-Byte Target

To fit inside 1 KB (1024 raw bytes of source code in C), we need strict scope boundaries. The mini-interpreter must parse source code, manage memory, and execute logic sequentially.

Here is what our micro-runtime supports:

• Single-letter integer variables (a through z).
• Arithmetic operations (+, -, *, /).
• Comparisons and assignments (=, ==, <).
• Control flow (while loops and if statements).
• Output via an explicit print operator.

Here is what gets tossed out immediately:

• Heap memory management and garbage collection.
• Multi-letter identifier lookup tables (bypassing usual variable naming best practices).
• Floating-point numbers (everything is a signed 32-bit integer).
• Functions, classes, and object models.

By dropping heap allocations, all variable storage maps directly to a static array of 26 integers. The symbol table lookup morphs from a hash map read into a single array offset calculation: var_name - 'a'.

Architecture of a Micro-Runtime

A tiny interpreter divides into three distinct passes. Normally, these passes run sequentially with intermediate data structures:

1. Scanner / Lexer: Converts raw source strings into token streams.
2. Compiler: Converts token streams into an instruction array (bytecode).
3. Virtual Machine (VM): Iterates over instructions and updates an execution stack.

To keep our footprint under 1024 bytes, we combine scanning and compiling into a single recursive-descent pass. The parser reads characters directly from the source buffer, converts them into compact instruction bytes, and writes them straight into a static memory vector.

Source Code (Text)
       │
       ▼
 [ Direct-Pass Parser ] ─── (Emits 1-Byte Opcodes)
       │
       ▼
 [ Instruction Buffer ]
       │
       ▼
 [ Stack-Based VM Loop ] ─── (Updates State Array & STDOUT)

The virtual machine uses an evaluation stack to process arithmetic expressions. Operators pop arguments from the stack and push results back.

Defining the Instruction Set

We map execution primitives to tiny, 1-byte opcodes. Each opcode represents a fundamental machine operation.

enum Op {
    OP_PUSH,      // Push immediate 32-bit int value
    OP_LOAD,      // Read variable index to stack
    OP_STORE,     // Pop stack value into variable index
    OP_ADD,       // Pop two, add, push result
    OP_SUB,       // Pop two, subtract, push result
    OP_MUL,       // Pop two, multiply, push result
    OP_DIV,       // Pop two, divide, push result
    OP_CMP_EQ,    // Compare top two for equality
    OP_CMP_LT,    // Compare top two for less-than
    OP_JUMP_IF,   // Conditional jump (used for if/while)
    OP_JUMP,      // Unconditional jump
    OP_PRINT,     // Pop stack and print integer
    OP_HALT       // Stop execution
};

Because operands for operators live on the evaluation stack, most opcodes require zero extra parameter bytes. Only OP_PUSH (which carries an integer payload), OP_LOAD/OP_STORE (which carry variable IDs), and jump instructions (which carry instruction pointer offsets) require payload bytes inside the bytecode array.

Writing the Bytecode Compiler

In an unconstrained interpreter, you build full parsing trees to handle operator precedence (* and / running before + and -). In a single-kilobyte footprint, we implement operator precedence using a minimal recursive descent structure.

The expression parser splits into three compact functions: factor(), term(), and expr().

• factor() handles raw integers, variable lookups, and parenthetical groups ( expr ).
• term() binds multiplication and division operators tightly.
• expr() binds addition and subtraction.

// Compact recursive expression evaluation
void expr();
 
void factor() {
    skip_whitespace();
    if (*src >= '0' && *src <= '9') {
        int val = 0;
        while (*src >= '0' && *src <= '9') {
            val = val * 10 + (*src++ - '0');
        }
        emit(OP_PUSH);
        emit_int(val);
    } else if (*src >= 'a' && *src <= 'z') {
        emit(OP_LOAD);
        emit(*src++ - 'a');
    } else if (*src == '(') {
        src++; // Skip '('
        expr();
        src++; // Skip ')'
    }
}
 
void term() {
    factor();
    while (*src == '*' || *src == '/') {
        char op = *src++;
        factor();
        emit(op == '*' ? OP_MUL : OP_DIV);
    }
}
 
void expr() {
    term();
    while (*src == '+' || *src == '-') {
        char op = *src++;
        term();
        emit(op == '+' ? OP_ADD : OP_SUB);
    }
}

This tiny structure handles arbitrary mathematical nesting. Writing (a + 5) * 2 correctly compiles into:

OP_LOAD  0       ; Loads variable 'a'
OP_PUSH  5       ; Pushes integer 5
OP_ADD           ; Computes a + 5
OP_PUSH  2       ; Pushes integer 2
OP_MUL           ; Computes (a + 5) * 2

Implementing Control Flow Without a Symbol Table

Handling statements like while a < 10: presents an immediate problem. When emitting a conditional jump at the start of a loop, the compiler does not yet know the byte offset of the end of the loop block.

In full compilers, you solve this with multi-pass AST processing or backpatching lists. For our micro-engine, backpatching works cleanly with minimal code overhead.

When compiling an if or while statement:

1. Emit OP_JUMP_IF into the bytecode stream.
2. Record the current bytecode index position of the jump destination argument.
3. Emit a dummy location value (e.g., 00 00).
4. Parse the body of the control block.
5. Calculate how many bytes were generated during step 4.
6. Overwrite the dummy location at step 2 with the real offset.

Here is how that backpatching logic looks inside a statement parser loop:

void statement() {
    skip_whitespace();
    if (strncmp(src, "while", 5) == 0) {
        src += 5;
        int loop_start = code_len;
        
        expr(); // Parse condition evaluation
        
        emit(OP_JUMP_IF);
        int jump_patch_pos = code_len;
        emit_int(0); // Placeholder offset
        
        skip_colon_and_newline();
        while (*src == ' ' || *src == '\t') { // Simple indentation check
            statement();
        }
        
        // Loop back to condition
        emit(OP_JUMP);
        emit_int(loop_start);
        
        // Backpatch jump position to exit loop
        patch_int(jump_patch_pos, code_len);
    } else if (isalpha(*src) && *(src + 1) == '=') {
        char var_id = *src - 'a';
        src += 2; // Skip 'x='
        expr();
        emit(OP_STORE);
        emit(var_id);
    } else if (strncmp(src, "print", 5) == 0) {
        src += 5;
        expr();
        emit(OP_PRINT);
    }
}

This approach tracks jump targets entirely in place. We don't allocate symbol tables, jump labels, or temporary AST structures. The compiler writes instructions directly into a flat uint8_t byte array while patching forward jumps on the fly.

The Virtual Machine Evaluation Loop

Once parsing completes, execution reduces to a basic switch statement running inside an infinite loop. The VM maintains an instruction pointer ip, a stack pointer sp, an integer stack, and a variable store array.

void execute(uint8_t *code) {
    int stack[256];
    int vars[26] = {0};
    int sp = 0;
    int ip = 0;
 
    while (1) {
        uint8_t opcode = code[ip++];
        switch (opcode) {
            case OP_PUSH:
                stack[sp++] = read_int_at(code, &ip);
                break;
            case OP_LOAD:
                stack[sp++] = vars[code[ip++]];
                break;
            case OP_STORE:
                vars[code[ip++]] = stack[-sp];
                break;
            case OP_ADD:
                stack[sp - 2] = stack[sp - 2] + stack[sp - 1];
                sp-;
                break;
            case OP_SUB:
                stack[sp - 2] = stack[sp - 2] - stack[sp - 1];
                sp-;
                break;
            case OP_MUL:
                stack[sp - 2] = stack[sp - 2] * stack[sp - 1];
                sp-;
                break;
            case OP_DIV:
                stack[sp - 2] = stack[sp - 2] / stack[sp - 1];
                sp-;
                break;
            case OP_CMP_LT:
                stack[sp - 2] = (stack[sp - 2] < stack[sp - 1]) ? 1 : 0;
                sp-;
                break;
            case OP_JUMP_IF: {
                int target = read_int_at(code, &ip);
                int cond = stack[-sp];
                if (!cond) ip = target;
                break;
            }
            case OP_JUMP:
                ip = read_int_at(code, &ip);
                break;
            case OP_PRINT:
                printf("%d\n", stack[-sp]);
                break;
            case OP_HALT:
                return;
        }
    }
}

Notice how binary operators modify stack[sp - 2] directly before dropping sp. That avoids extra push/pop buffer operations and cuts double-digit bytes out of the binary footprint.

The Complete 1024-Byte C Engine

Combining these compiler routines and the execution loop into a single source file yields a completely functional micro-interpreter. When golfed-removing extra spaces, collapsing single-line blocks, and merging helper routines-the source drops below 1024 total bytes.

#include <stdio.h>
#include <ctype.h>
#include <string.h>
 
enum{P,L,S,A,B,M,D,C,J,G,R,H};
unsigned char c[1024],*p=c,*s;
int v[26],st[256],sp,ip;
 
void e();
void f(){
 while(*s==' ')s++;
 if(isdigit(*s)){
  int n=0;while(isdigit(*s))n=n*10+(*s++-'0');
  *p++=P;*(int*)p=n;p+=4;
 }else if(isalpha(*s)){
  *p++=L;*p++=*s++-'a';
 }else if(*s=='('){s++;e();s++;}
}
void t(){f();while(*s=='*'||*s=='/'){char o=*s++;f();*p++=(o=='*')?M:D;}}
void e(){t();while(*s=='+'||*s=='-'){char o=*s++;t();*p++=(o=='+')?A:B;}}
 
void compile(char *in){
 s=in;
 while(*s){
  while(*s==' '||*s=='\n'||*s=='\t')s++;
  if(!*s)break;
  if(strncmp(s,"print",5)==0){s+=5;e();*p++=R;}
  else if(strncmp(s,"while",5)==0){
   s+=5;int ls=p-c;e();
   if(*s=='<'){s++;*p++=C;}
   *p++=J;int jp=p-c;p+=4;
   while(*s!=':')s++;s++;
   while(*s==' '||*s=='\t'||*s=='\n'||isalpha(*s))if(strncmp(s,"print",5)==0||isalpha(*s)){
    if(strncmp(s,"print",5)==0){s+=5;e();*p++=R;}
    else if(isalpha(*s)&&*(s+1)=='='){int id=*s-'a';s+=2;e();*p++=S;*p++=id;}
    break;
   }
   *p++=G;*(int*)p=ls;p+=4;
   *(int*)(c+jp)=(int)(p-c);
  }
  else if(isalpha(*s)&&*(s+1)=='='){int id=*s-'a';s+=2;e();*p++=S;*p++=id;}
  else s++;
 }
 *p++=H;
}
 
void run(){
 ip=0;
 while(1){
  switch(c[ip++]){
   case P:st[sp++]=*(int*)(c+ip);ip+=4;break;
   case L:st[sp++]=v[c[ip++]];break;
   case S:v[c[ip++]]=st[-sp];break;
   case A:st[sp-2]+=st[sp-1];sp-;break;
   case B:st[sp-2]-=st[sp-1];sp-;break;
   case M:st[sp-2]*=st[sp-1];sp-;break;
   case D:st[sp-2]/=st[sp-1];sp-;break;
   case C:st[sp-2]=(st[sp-2]<st[sp-1]);sp-;break;
   case J:if(!st[-sp])ip=*(int*)(c+ip);else ip+=4;break;
   case G:ip=*(int*)(c+ip);break;
   case R:printf("%d\n",st[-sp]);break;
   case H:return;
  }
 }
}
 
int main(){
 char *code = "a = 1\nwhile a < 5:\n print a\n a = a + 1\n";
 compile(code);
 run();
 return 0;
}

The C code above sits at roughly 940 bytes. Compiling it with aggressive machine-code optimization yields an ultra-small executable:

gcc -Os -s -fno-asynchronous-unwind-tables mini_py.c -o mini_py

Running ls -la mini_py reveals an executable payload that executes standard Python-like loop and print structures directly from raw text.

Verification of Execution Capabilities

Let's test this minimal engine against a classic sequence generation script. Consider the following code string passed into compile():

a = 0
b = 1
c = 0
while c < 10:
    print a
    t = a + b
    a = b
    b = t
    c = c + 1

Here is what happens under the hood as the micro-interpreter processes this block:

1. a = 0 and b = 1 populate slots v[0] and v[1].
2. The while c < 10 loop evaluates v[2] < 10. It pushes 1 to the evaluation stack, triggering the non-zero branch check.
3. print a pops v[0] off the stack and outputs 0 to standard output.
4. t = a + b computes the next Fibonacci step into variable slot v[19].
5. The unpatched jump target rewinds execution straight to the top of the condition check until v[2] reaches 10.

Output generated:

0
1
1
2
3
5
8
13
21
34

The runtime executes all steps using fewer than 256 bytes of total runtime RAM for stack and symbol management. Similar techniques for cutting overhead can be seen in projects where Rust Glancer cuts language server memory overhead by rethinking core index structures.

Real World Limitations vs. Engineering Lessons

Building an execution model inside 1024 bytes requires accepting major trade-offs. This micro-interpreter lacks robust error handling. Passing malformed source syntax won't produce a helpful syntax error or line trace. It will likely throw a segmentation fault or enter an infinite loop.

The point of this exercise isn't production deployments. The point is learning how language runtimes work when stripped of enterprise machinery.

Modern virtual machines like CPython, V8, and the JVM add thousands of lines of safety code, garbage collection tracking, inline caching, and tracebacks. But deep down, every stack-based runtime relies on the exact pattern shown here: a parser that emits instruction sequences, and an execution loop that cycles through opcodes, updates a data stack, and reads state array cells.

Constraints clarify architecture. Strip away the fluff, and a complete virtual machine can fit on a single printed index card.