ox_inventory for FiveM

At a glance

Figures read from the repository on 2026-09-22.

Why servers run it

• Weapons are items. A gun in ox_inventory has weight, durability, an ammo type and a serial, and it moves between slots like anything else — no parallel weapon table to keep in sync.
• It is framework independent. The same data/items.lua works whether the server runs ESX Legacy, QBCore, Qbox or ox_core, which is why third-party scripts target it by default.
• Metadata is per slot, not per item name. Two identical pistols can carry different durability, serials and registration — the thing a roleplay server actually needs.
• The UI is a React app served over NUI, so item images are ordinary PNG files you can drop in rather than a spritesheet you have to rebuild.

Installing ox_inventory

1. 1. Install the dependencies first

   ox_inventory needs ox_lib and oxmysql. Start them before it in server.cfg — a missing ox_lib is the single most common reason ox_inventory refuses to start.

2. 2. Drop the resource in

   Put the ox_inventory folder in your resources directory. Do not rename it: every other script that integrates with it calls exports.ox_inventory by that exact name.

3. 3. Run the SQL

   The repository ships a setup SQL file. It creates the inventory tables and, depending on your framework, alters the characters table to hold the inventory column.

4. 4. Point it at your framework

   Open fxmanifest.lua and set the framework convar, or set setr inventory:framework in server.cfg. Getting this wrong produces an inventory that loads but never saves.

5. 5. Start it in the right order

   ensure oxmysql, then ox_lib, then ox_inventory, then everything that depends on it. Load order is not cosmetic here.

Working examples

-- Every addon weapon needs an entry here before the inventory will accept it.
-- The key is the WEAPON_ name; the hash is derived from it, so it must match
-- the name your weapons.meta declares exactly.

['WEAPON_CUSTOMPISTOL'] = {
    label = 'Custom Pistol',
    weight = 1000,          -- grams
    durability = 0.1,       -- % lost per shot
    ammoname = 'ammo-9',    -- shared ammo pool, not per weapon
},

['WEAPON_CUSTOMRIFLE'] = {
    label = 'Custom Rifle',
    weight = 3300,
    durability = 0.03,
    ammoname = 'ammo-rifle',
},

-- addItem takes the item name, a count and optional metadata. For a weapon
-- the metadata is where the serial, durability and registration live.

exports.ox_inventory:AddItem(source, 'WEAPON_CUSTOMPISTOL', 1, {
    serial = 'PTY-' .. math.random(100000, 999999),
    durability = 100,
    registered = 'John Doe',
})

-- Ammo is a separate item and uses the ammoname from data/weapons.lua
exports.ox_inventory:AddItem(source, 'ammo-9', 60)

local count = exports.ox_inventory:Search(source, 'count', 'WEAPON_CUSTOMPISTOL')
if count > 0 then
    -- They have at least one. Search with 'slots' instead to read the
    -- metadata of each individual copy.
    local slots = exports.ox_inventory:Search(source, 'slots', 'WEAPON_CUSTOMPISTOL')
    print(slots[1].metadata.serial)
end

What goes wrong

ox_inventory — questions people ask

Runs alongside