table.insert

table.insert(list, [pos,] value)

Returns nil· Updated May 19, 2026· Table Methods

luatablearrayinserttable-methods

table.insert puts a value into the array part of a table. With two arguments it appends to the end. With three arguments it inserts at the given position and shifts every element from that position onward up by one. The function mutates the table in place and returns nothing.

Signature

table.insert(list, value)
table.insert(list, pos, value)

list , the table being modified (treated as a 1-based array).
pos , optional 1-based position. Defaults to #list + 1.
value , the value to insert.

Appending to an array

The two-argument form is the everyday case:

local fruits = {"apple", "banana"}
table.insert(fruits, "cherry")
-- fruits == {"apple", "banana", "cherry"}
print(#fruits)   --> 3

This is equivalent to fruits[#fruits + 1] = "cherry" but reads more clearly when the intent is “push onto an array.”

Inserting at a position

The three-argument form shifts later elements up:

local letters = {"a", "b", "d"}
table.insert(letters, 3, "c")
-- letters == {"a", "b", "c", "d"}

Inserting at the front:

local q = {"second", "third"}
table.insert(q, 1, "first")
-- q == {"first", "second", "third"}

Inserting at a position past #list + 1 is undefined behaviour in Lua 5.4 , don’t do it. Stick to indices in 1 .. #list + 1.

Cost

Inserting at the end is O(1). Inserting at position p is O(#list - p + 1) because every element after p shifts one slot. For large arrays where you mostly prepend or insert in the middle, consider a linked list or a different data structure.

Use as a stack/queue

Combined with table.remove, table.insert powers stack and queue patterns:

-- Stack: push and pop at the end
local stack = {}
table.insert(stack, "a")
table.insert(stack, "b")
local top = table.remove(stack)   -- "b"

-- Queue: enqueue at the end, dequeue at the front
local queue = {}
table.insert(queue, "task1")
table.insert(queue, "task2")
local next_task = table.remove(queue, 1)   -- "task1"

For long-running queues, dequeuing at position 1 is O(n); reach for a ring buffer when throughput matters.

Holes and the length operator

table.insert works on the array part of the table. If you’ve put nil in the middle of an array, #list may report any boundary, which means table.insert(list, value) could land in an unexpected slot. Keep arrays dense or track length manually when holes are possible.

local t = {1, 2, nil, 4}
-- #t may be 2 or 4 depending on the Lua implementation
table.insert(t, "x")   -- position depends on #t

Method syntax

table.insert is not a method on table values , there is no t:insert(v). Always call it as table.insert(t, v).