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

# Run an ES module
qjs module.mjs

# Or explicitly specify module mode
qjs --module app.js

# Pass arguments to the script
qjs app.js arg1 arg2 arg3

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

flag

Display help information and list all available options

string

Evaluate the given expression and exit

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

flag

Enter interactive REPL mode after running scripts or expressions

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

flag

Instantiate the interpreter and quit immediately (useful for testing)

Module Loading

flag

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

qjs --module app.js

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)

string

Include an additional file before running the main script

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

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

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

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

flag

Enable memory allocation tracing for debugging memory issues

qjs --trace script.js

flag

Dump memory usage statistics when the runtime exits

qjs --dump script.js

hex

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

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

Compilation Options

string

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

qjs -c app.js -o app

string

Specify the output filename for standalone executables

qjs -c app.js -o myapp

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

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

​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

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