How to Install and Configure ox_inventory on Your FiveM Server

ox_inventory has become the de facto standard inventory system for FiveM servers in 2025. It is fast, feature-rich, actively maintained by the Overextended team, and supported by a huge and growing number of scripts from both ESX and QBCore ecosystems. This guide covers a complete, correct installation.

Why ox_inventory?

Before diving into the install, here is why most serious servers choose ox_inventory over built-in framework inventories:

• Performance — Significantly lower resource usage than alternatives
• Feature set — Drag-and-drop UI, weight system, item metadata, weapon attachments, and more
• Active development — Regular updates and bug fixes from a dedicated team
• Script compatibility — The majority of premium scripts now target ox_inventory first

---

Prerequisites

Make sure these are already installed and working before you start:

• A FiveM server running QBCore or ESX Legacy
• oxmysql installed and connected to your MySQL database
• ox_lib installed (ox_inventory depends on it for shared utilities)

---

Step 1: Install ox_lib First

ox_inventory requires ox_lib to be installed and running. Install it before anything else:

git clone https://github.com/overextended/ox_lib resources/[ox]/ox_lib

Add it to server.cfg and make sure it loads before ox_inventory:

ensure ox_lib

---

Step 2: Download ox_inventory

git clone https://github.com/overextended/ox_inventory resources/[ox]/ox_inventory

Alternatively, download the latest stable release ZIP from the GitHub releases page and extract it into your resources folder.

---

Step 3: Import the SQL File

ox_inventory requires a database table to persist inventory data between sessions. Import the included SQL file:

mysql -u root -p your_database < resources/[ox]/ox_inventory/ox_inventory.sql

Or use HeidiSQL → File → Run SQL File → select ox_inventory.sql.

Verify the ox_inventory table was created in your database before proceeding.

---

Step 4: Configure ox_inventory

Open ox_inventory/data/config.lua. The most important settings:

-- Which framework you are using
inventory.framework = 'qb'  -- options: 'qb', 'esx', 'ox', 'none'

-- Inventory slot and weight limits
inventory.playerSlots  = 50
inventory.playerWeight = 30000

-- How players are identified in the database
inventory.identifyType = 'license'  -- match your framework's identifier type

-- Weapon durability system
inventory.weaponDurability = true

---

Step 5: Add to server.cfg

The full correct load order with ox_inventory:

ensure oxmysql
ensure ox_lib
ensure qb-core
ensure ox_inventory

ox_inventory must load after both ox_lib and your framework. Any scripts that use ox_inventory must load after ox_inventory itself.

---

Step 6: Bridge to Your Framework

For QBCore: Tell QBCore not to use its own built-in inventory system. In qb-core/shared/config.lua:

QBShared.ShouldUseInventory = false

For ESX: ox_inventory replaces the default ESX inventory automatically when inventory.framework is set to 'esx'. No additional config needed.

---

Step 7: Register Your Items

All item definitions live in ox_inventory/data/items.lua. Every item that any script uses must be registered here. A typical item entry:

['water'] = {
    label       = 'Water',
    weight      = 500,
    stack       = true,
    close       = true,
    description = 'A bottle of water',
    consume     = 1,
},

['phone'] = {
    label       = 'Phone',
    weight      = 200,
    stack       = false,
    close       = false,
    unique      = true,
    description = 'A smartphone',
},

When you install new scripts that require items, add their item definitions to this file. Scripts that reference unregistered items will show "Unknown Item" in the inventory UI and fail to function correctly.

---

Step 8: Add Item Images

ox_inventory displays images for each item in its grid UI. Images go in:

ox_inventory/web/images/

The filename must match the item name exactly — for an item named water, the image file must be water.png.

Free community item image packs are available on GitHub. Search "ox_inventory item images" to find packs that match your item set and drop all the .png files into that directory.

---

Step 9: Test the Inventory

Start your server, connect, and press Tab to open the inventory. Verify:

• The ox_inventory grid UI opens correctly
• You can add items via admin commands and see them appear
• Items can be dragged between inventory slots
• The hotbar (number keys) functions correctly
• Dropping an item from the inventory works

---

Common Issues and Solutions

ox_inventory: framework not found — Either ox_lib or your framework is not loading before ox_inventory. Fix the load order in server.cfg.

Items show as "Unknown Item" — The item is not registered in items.lua. Add its definition.

Inventory UI opens but is blank when it should not be — The SQL import may have failed silently. Open HeidiSQL and confirm the ox_inventory table exists and contains rows for the player.

attempt to index nil (ox_lib) — ox_lib is not installed or is not listed in server.cfg. Add ensure ox_lib above ensure ox_inventory.

---

Browse ox_inventory-compatible scripts — all listings on ModForge clearly show inventory compatibility. Start at modforge.xyz.