How to Install & Configure OX Inventory in FiveM – Complete Guide for ESX, QBCore & QBOX [2026]

What Is OX Inventory in FiveM?

Unlike traditional legacy inventories that treat items as simple numbers in a database table, OX Inventory introduces:

• Grid-based slot management: Drag-and-drop mechanics with customizable inventory sizes, weights, and dimensions.
• True item metadata & durability: Individual serial numbers on firearms, food spoilage timers, weapon wear-and-tear, and custom item data.
• Physical weapon items: Guns are real items in your pockets that require ammo boxes, magazines, and attachments (suppressors, scopes, flashlights, grips).
• Comprehensive storage ecosystem: Seamless built-in support for vehicle trunks, gloveboxes, personal lockers, criminal stashes, player-to-player trading, and drop items.
• Built-in crafting & shop systems: Integrated modular shops, vending machines, custom workbenches, and black markets with zero extra scripts required.
• Zero-lag architecture: Powered by ox_lib and oxmysql, running at a steady 0.00ms to 0.01ms tick rate on client and server.

Whether you're building a serious roleplay server, a hardcore survival server, or an action-packed gang economy, OX Inventory is the backbone that powers modern FiveM gameplay.

Why Choose OX Inventory Over Default Inventories

Did you know? Many premium resources and scripts on FiveVault come pre-configured with native OX Inventory items, icons, and export hooks. Browse all scripts on FiveVault →

Prerequisites

Step 1: Install Core Dependencies

Before installing OX Inventory itself, you must install and verify its two core prerequisites: oxmysql and ox_lib.

1. Download the latest compiled release of oxmysql and place it in your resources/[core]/ or resources/[ox]/ folder.
2. Download the latest compiled release of ox_lib and place it in your resources/[ox]/ folder.

Pro tip: Always download the .zip archive from the Releases tab on GitHub (e.g., ox_lib.zip), NOT the green "Source code (zip)" button. Source builds do not include compiled UI assets and will fail to open in-game.

Your folder structure should look like this:

resources/
└── [ox]/
    ├── oxmysql/
    ├── ox_lib/
    └── ox_inventory/

Step 2: Download & Extract ox_inventory

1. Navigate to the official ox_inventory GitHub Releases page.
2. Download the compiled release archive ox_inventory.zip.
3. Extract the contents into your server's resources/[ox]/ directory.

Confirm your directory structure contains the following essential files:

ox_inventory/
├── client/
├── data/
│   ├── items.lua
│   ├── weapons.lua
│   ├── shops.lua
│   └── craft.lua
├── locales/
├── modules/
├── server/
├── web/
│   └── build/
│       └── index.html
├── fxmanifest.lua
└── init.lua

Pro tip: Check that ox_inventory/web/build/index.html exists. If the web/build/ folder is empty, you downloaded raw source code instead of the compiled release package.

Step 3: Configure Database & Automatic Schema Migration

OX Inventory handles most of its database creation automatically upon first boot when connected to oxmysql. However, you should ensure your oxmysql connection string is properly set in your server.cfg before starting.

Verify your MySQL connection string format in server.cfg:

set mysql_connection_string "mysql://user:password@localhost/fivem_server?charset=utf8mb4"
set mysql_ui true

When OX Inventory starts for the first time, it will automatically create and update the necessary tables:

• ox_inventory (Stores personal player inventories, gloveboxes, trunks, and custom stashes)
• Integrates with your framework's character tables (users for ESX or players for QBCore/QBOX)

Step 4: Configure server.cfg & Startup Convars

OX Inventory uses FiveM console variables (convars) placed in server.cfg to control framework compatibility, keybinds, inventory weights, and features.

Add the following configuration block to your server.cfg before any resources are started:

# ===================================================
# OX INVENTORY CONVARS (Must be above 'ensure' lines)
# ===================================================

# Set your framework: 'esx', 'qb', 'qbox', or 'ox'
setr inventory:framework "qb"

# Inventory screen keybind (Default: F2 or TAB)
setr inventory:screen "F2"

# Default inventory parameters
setr inventory:slots 50
setr inventory:weight 30000

# Target system integration: true (ox_target/qb-target) or false (keys/markers)
setr inventory:target true

# Weapon mechanics
setr inventory:weaponitems true
setr inventory:autoreload false
setr inventory:durability true

# Drop items
setr inventory:dropprops true
setr inventory:dropmodel "prop_paper_bag_01"

# Logs & Discord Webhooks (Optional)
set inventory:webhook ""
set inventory:loglevel 1

Framework Convar Values

Step 5: Adjust Load Order in server.cfg

Resource starting order is crucial. oxmysql and ox_lib must load before your framework and ox_inventory.

Update your server.cfg load order as follows:

# Database & Core Libs
ensure oxmysql
ensure ox_lib

# Framework Core
ensure qb-core          # Or es_extended / qbx_core

# Target System (If used)
ensure ox_target        # Or qb-target

# OX Inventory (Starts AFTER framework and ox_lib)
ensure ox_inventory

# Other scripts, vehicles, and MLOs
ensure [scripts]
ensure [maps]
ensure [vehicles]

Step 6: Disable Default Framework Inventories

To prevent keybind conflicts, duplicate HUDs, and inventory crashes, you must disable the default inventory resource included with your framework base.

If You Use QBCore:

1. Open your server.cfg and ensure qb-inventory is NOT being started.
2. In your resources folder, add qb-inventory to a [disabled] folder or delete it.
3. Open qb-core/config.lua and set:

   QBConfig.Server.ItemWeapons = false -- ox_inventory handles weapon items natively
   

1. If using qb-weapons, disable or remove it, as OX Inventory handles weapon attachments, ammo, and durability automatically.

If You Use ESX:

1. Ensure esx_inventoryhud or standard esx_menu_default inventory screens are commented out in server.cfg.
2. Disable esx_weapons and esx_weaponshop, replacing shop points with OX Inventory built-in shops.

Step 7: Managing Items, Weapons & Item Icons

OX Inventory stores all item definitions inside the data/ directory rather than requiring manual database queries for every single item.

ox_inventory/
└── data/
    ├── items.lua       -- Normal consumable & usable items
    ├── weapons.lua     -- Firearms, melee weapons & attachments
    └── shops.lua       -- In-game stores, 24/7, ammunation, vending machines

Adding a Custom Item to data/items.lua

To add a new custom item, open ox_inventory/data/items.lua and append your definition:

['energy_drink'] = {
    label = 'Red Bull Energy',
    weight = 250,
    stack = true,
    close = true,
    description = 'Restores your stamina and gives a quick boost.',
    client = {
        image = 'energy_drink.png',
        status = { thirst = 200000 },
        anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' },
        prop = { model = 'prop_energy_drink', pos = vec3(0.01, -0.01, -0.06), rot = vec3(5.0, 5.0, -180.5) },
        usetime = 2500,
    }
},

Adding Custom Item Icons

1. Prepare your icon as a transparent PNG image (recommended size: 100x100 or 128x128 pixels).
2. Name the file to match the item name (e.g., energy_drink.png).
3. Place the file inside:

   ox_inventory/web/images/
   

1. Restart the resource or run refresh in console to load the new texture.

Step 8: Vehicle Storage (Trunks & Gloveboxes)

OX Inventory automatically creates vehicle gloveboxes and trunks for any spawned vehicle based on its vehicle class.

You can customize vehicle capacity, weights, and slot limits globally in data/vehicles.lua:

-- data/vehicles.lua
return {
    ['sedans'] = {
        trunk = { slots = 35, maxWeight = 45000 },
        glovebox = { slots = 5, maxWeight = 5000 }
    },
    ['suvs'] = {
        trunk = { slots = 50, maxWeight = 70000 },
        glovebox = { slots = 5, maxWeight = 5000 }
    },
    ['super'] = {
        trunk = { slots = 15, maxWeight = 20000 },
        glovebox = { slots = 3, maxWeight = 3000 }
    }
}

To open a vehicle trunk in-game:

• With Target (ox_target): Look at the vehicle trunk and select "Open Trunk".
• With Command / Hotkey: Stand near the rear of the vehicle and type /trunk or press your assigned interaction key.

Framework Compatibility Matrix

Key Convars Reference

Troubleshooting Common OX Inventory Issues

❌ Inventory UI will not open (Black screen or nothing happens on key press)

1. Check that you downloaded the compiled release package containing web/build/index.html. If you cloned the repository or downloaded source code without running npm run build, the NUI interface will not render.
2. Verify that inventory:screen convar in server.cfg is not conflicting with another script using the same keybind.
3. Open F8 console in-game to check for missing client-side JavaScript or CSS errors.

❌ "ox_lib is missing or loaded after ox_inventory" error in console

In server.cfg, ensure ensure ox_lib appears above ensure ox_inventory. OX Inventory relies on ox_lib exports immediately when initiating its runtime.

❌ Default GTA V weapon wheel still appears on weapon switch

Ensure you have setr inventory:weaponitems true in server.cfg. Additionally, verify that no standalone weapon wheel script or legacy framework resource is reenabling the weapon wheel native (SetPedConfigFlag / DisablePlayerFiring).

❌ Items disappear or reset after server restart

1. Check your txAdmin / server console for oxmysql query timeouts.
2. Confirm the ox_inventory table was created in your database.
3. Ensure your server is shut down cleanly using txAdmin's scheduled restarts or the quit command so state saves to the database.

❌ Trunk or glovebox won't open on custom add-on cars

Custom addon vehicles may lack standard GTA V vehicle classes or metadata. Open data/vehicles.lua and register the specific model spawn name under custom overrides with explicit slot and weight settings.

❌ Custom item icon shows as a broken image placeholder

1. Verify the image file is placed in ox_inventory/web/images/.
2. Ensure the image is formatted as a .png file in lowercase (e.g., phone.png, not Phone.PNG). Linux server environments are strictly case-sensitive.
3. Ensure the item name in data/items.lua matches the filename exactly.

Recommended Scripts That Pair Great With OX Inventory

Final Tips

• ✅ Always download the GitHub Releases build, not the green "Source Code" button.
• ✅ Place convars at the top of server.cfg before any ensure statements run.
• ✅ Disable default inventories completely to avoid keybind clashing and duplicate items.
• ✅ Use lowercase filenames for PNG icons to avoid Linux file system loading issues.
• ✅ Keep items organized in data/items.lua using clean descriptive naming and categories.
• ✅ Set up regular database backups before executing major inventory migrations.
• ✅ Test trunk and stash capacities on dev servers with various vehicle types.

Frequently Asked Questions

A: Yes, but you will need an inventory migration script (such as the built-in converters provided in the Overextended documentation) to convert existing SQL player inventory columns into the ox_inventory database format.

A: Use the built-in command /giveitem [playerId] [itemName] [count] [metadata] (e.g., /giveitem 1 bread 5).

A: Yes. You can register any custom weapon in data/weapons.lua with its weapon hash, ammo type, attachments, and durability values.

A: Change setr inventory:screen "F2" to setr inventory:screen "TAB" in your server.cfg. Players can also rebind this in their GTA V key mapping settings under FiveM.

A: Yes. When a player has their hands up or is restrained, other players can target them via ox_target to open their inventory and search/steal items based on your configured permissions.