qjs - QuickJS Interpreter

The qjs executable is the QuickJS JavaScript interpreter. It includes a simple standard library and an interactive REPL (Read-Eval-Print Loop).

Basic Usage

qjs [options] [file [args]]

Running JavaScript Files

# Run a JavaScript file (auto-detected as script)
qjs script.js

Interactive REPL

# Start interactive mode
qjs

# Or explicitly request interactive mode
qjs -i
qjs --interactive

Evaluate Expressions

# Evaluate a single expression
qjs -e "console.log('Hello World')"

# Evaluate and enter interactive mode
qjs -e "const x = 42" -i

Command-Line Options

General Options

-h, --help

flag

Display help information and list all available options

-e, --eval EXPR

string

Evaluate the given expression and exit

qjs -e "console.log(Math.PI)"

-i, --interactive

flag

Enter interactive REPL mode after running scripts or expressions

qjs -e "const greeting = 'Hi'" -i

-q, --quit

flag

Instantiate the interpreter and quit immediately (useful for testing)

Module Loading

-m, --module

flag

Load the file as an ES6 module (default=autodetect)

qjs --module app.js

-C, --script

flag

Load the file as a classic JavaScript script (default=autodetect)

qjs --script legacy.js

By default, qjs automatically detects whether to load a file as a module or script based on:

File extension (.mjs files are modules)
Content analysis (presence of import/export statements)

-I, --include FILE

string

Include an additional file before running the main script

qjs --include polyfills.js --include helpers.js main.js

--std

flag

Make the std, os, and bjson modules available globally to the script

qjs --std script.js

This makes the modules accessible without imports:

// Available when using --std flag
std.printf("Hello %s\n", "World");
const file = std.open("data.txt", "r");

Memory and Performance

--memory-limit N

string

Limit memory usage to N kilobytes (supports b, k, m, g suffixes)

# Limit to 10 megabytes
qjs --memory-limit 10m script.js

# Limit to 512 kilobytes
qjs --memory-limit 512k script.js

--stack-size N

string

Limit stack size to N kilobytes (supports b, k, m, g suffixes)

# Set stack size to 1 megabyte
qjs --stack-size 1m script.js

Setting memory or stack limits too low may cause scripts to fail with out-of-memory errors.

Debugging and Diagnostics

-T, --trace

flag

Enable memory allocation tracing for debugging memory issues

qjs --trace script.js

-d, --dump

flag

Dump memory usage statistics when the runtime exits

qjs --dump script.js

-D, --dump-flags FLAGS

hex

Set debug dump flags (hexadecimal value). See Dump Flags below.

# Dump bytecode and GC info
qjs --dump-flags 0x401 script.js

Compilation Options

-c, --compile FILE

string

Compile the JavaScript file into a standalone executableMust be used with -o to specify the output file.

qjs -c app.js -o app

-o, --out FILE

string

Specify the output filename for standalone executables

qjs -c app.js -o myapp

--exe FILE

string

Select the executable to use as the base for standalone builds (defaults to current qjs)

qjs -c app.js -o app --exe /usr/bin/qjs

Dump Flags

The --dump-flags option accepts a hexadecimal value combining these flags:

Flag	Value	Description
`DUMP_BYTECODE_FINAL`	`0x00001`	Dump pass 3 final bytecode
`DUMP_BYTECODE_PASS2`	`0x00002`	Dump pass 2 code
`DUMP_BYTECODE_PASS1`	`0x00004`	Dump pass 1 code
`DUMP_BYTECODE_HEX`	`0x00010`	Dump bytecode in hexadecimal
`DUMP_BYTECODE_PC2LINE`	`0x00020`	Dump line number table
`DUMP_BYTECODE_STACK`	`0x00040`	Dump compute_stack_size
`DUMP_BYTECODE_STEP`	`0x00080`	Dump executed bytecode
`DUMP_READ_OBJECT`	`0x00100`	Dump marshalled objects at load time
`DUMP_FREE`	`0x00200`	Dump every object free
`DUMP_GC`	`0x00400`	Dump automatic GC occurrences
`DUMP_GC_FREE`	`0x00800`	Dump objects freed by GC
`DUMP_MODULE_RESOLVE`	`0x01000`	Dump module resolution steps
`DUMP_PROMISE`	`0x02000`	Dump promise steps
`DUMP_LEAKS`	`0x04000`	Dump leaked objects and strings in JS_FreeRuntime
`DUMP_ATOM_LEAKS`	`0x08000`	Dump leaked atoms in JS_FreeRuntime
`DUMP_MEM`	`0x10000`	Dump memory usage in JS_FreeRuntime
`DUMP_OBJECTS`	`0x20000`	Dump objects in JS_FreeRuntime
`DUMP_ATOMS`	`0x40000`	Dump atoms in JS_FreeRuntime
`DUMP_SHAPES`	`0x80000`	Dump shapes in JS_FreeRuntime

Example: Debugging Memory Leaks

# Dump leaked objects and memory usage
qjs --dump-flags 0x14000 script.js

# Dump all GC activity
qjs --dump-flags 0xC00 script.js

Environment Variables

QJS_DUMP_FLAGS

hex

Set default dump flags via environment variable

export QJS_DUMP_FLAGS=0x400
qjs script.js  # Will dump GC activity

Global Objects

The qjs interpreter adds several global objects to the JavaScript environment:

`execArgv`

Array containing all command-line arguments:

// When run as: qjs script.js arg1 arg2
console.log(execArgv);  // ['script.js', 'arg1', 'arg2']

`argv0`

The first command-line argument (typically the script name):

console.log(argv0);  // 'script.js'

`navigator.userAgent`

Contains the QuickJS-ng version string:

console.log(navigator.userAgent);  // 'quickjs-ng/0.7.0'

`gc()`

Manually trigger garbage collection:

gc();  // Run garbage collector

Examples

Run a Simple Script

qjs -e "console.log('Hello World')"

Run with Standard Library

qjs --std -e "std.printf('PI = %.2f\\n', Math.PI)"

Debug Memory Usage

qjs --trace --dump script.js

Interactive REPL with Preloaded Code

qjs --include lib.js --include utils.js -i

Compile to Standalone Executable

qjs -c myapp.js -o myapp
./myapp  # Run the standalone executable

See Creating Standalone Executables for more details on compilation.

Exit Codes

0 - Success
1 - Script execution error or compilation failure
2 - Runtime/context allocation failure

Overview

Core Concepts

CLI Tools

Standard Library

Advanced Topics

Platform Support

qjs - QuickJS Interpreter

qjs - QuickJS Interpreter

Basic Usage

Running JavaScript Files

Interactive REPL

Evaluate Expressions

Command-Line Options

General Options

Module Loading

Memory and Performance

Debugging and Diagnostics

Compilation Options

Dump Flags

Example: Debugging Memory Leaks

Environment Variables

Global Objects

`execArgv`

`argv0`

`navigator.userAgent`

`gc()`

Examples

Run a Simple Script

Run with Standard Library

Debug Memory Usage

Interactive REPL with Preloaded Code

Compile to Standalone Executable

Exit Codes

See Also

Build docs developers (and LLMs) love

Overview

Core Concepts

CLI Tools

Standard Library

Advanced Topics

Platform Support

​qjs - QuickJS Interpreter

​Basic Usage

​Running JavaScript Files

​Interactive REPL

​Evaluate Expressions

​Command-Line Options

​General Options

​Module Loading

​Memory and Performance

​Debugging and Diagnostics

​Compilation Options

​Dump Flags

​Example: Debugging Memory Leaks

​Environment Variables

​Global Objects

​execArgv

​argv0

​navigator.userAgent

​gc()

​Examples

​Run a Simple Script

​Run with Standard Library

​Debug Memory Usage

​Interactive REPL with Preloaded Code

​Compile to Standalone Executable

​Exit Codes

​See Also

Build docs developers (and LLMs) love

qjs - QuickJS Interpreter

Basic Usage

Running JavaScript Files

Interactive REPL

Evaluate Expressions

Command-Line Options

General Options

Module Loading

Memory and Performance

Debugging and Diagnostics

Compilation Options

Dump Flags

Example: Debugging Memory Leaks

Environment Variables

Global Objects

`execArgv`

`argv0`

`navigator.userAgent`

`gc()`

Examples

Run a Simple Script

Run with Standard Library

Debug Memory Usage

Interactive REPL with Preloaded Code

Compile to Standalone Executable

Exit Codes

See Also