How to Set Up ox_inventory on FiveM

You’ve decided to install ox_inventory. Good call — it’s the one inventory script I actually recommend to new server owners without any caveats. The problem is the official docs assume you already know how FiveM resources work, and half the YouTube tutorials out there are from 2023 with outdated file paths.

I’ve installed ox_inventory on ESX, QBCore, and Qbox servers more times than I can count. Here’s the exact process that works in 2026, in the order you need to do it, with the errors you’ll hit and how to fix them.

Why You’re Installing ox_inventory in the First Place

Before we jump in, make sure this is the right script for your server. ox_inventory is free, performant, and works across every major framework, but it’s not a drop-in replacement that requires zero effort. If you’re not sure whether you should be running it versus qb-inventory, qs-inventory, or something else, I broke down the options in detail in my FiveM inventory comparison.

For everyone else — you’ve read the comparison, you know ox_inventory is the move, let’s get it installed.

Prerequisites — What You Need First

Don’t skip this section. Nine out of ten ox_inventory installation failures come from missing or mismatched dependencies.

You need:

A working FiveM server (if you don’t have one yet, start with my server setup guide)
txAdmin or direct file access to your server
MySQL or MariaDB database access (phpMyAdmin, HeidiSQL, or command line)
Your server framework already running (ESX Legacy 1.10+, QBCore latest, or Qbox)
Lua 5.4 enabled on your resource

That last one trips people up. ox_inventory requires Lua 5.4. If you copy it into a server still running Lua 5.3 resources, it will error on startup and you’ll have no idea why.

Step 1: Install oxmysql

ox_inventory does not use mysql-async. It uses oxmysql. If your server is still running mysql-async, you either need to replace it with oxmysql or run both in parallel (not recommended long-term).

Download the latest release from overextended/oxmysql on GitHub. Drop the folder into resources/[standalone]/oxmysql or wherever you keep shared dependencies.

Open your server.cfg and add your database connection string:

set mysql_connection_string "mysql://user:password@localhost/database?charset=utf8mb4"

Then ensure oxmysql starts before anything that touches the database:

ensure oxmysql

Restart the server and check your console. You should see:

[oxmysql] Database server connection established!

If you see a connection error, your credentials are wrong or MySQL isn’t running. Fix that before moving on. No database, no inventory.

Step 2: Install ox_lib

ox_inventory depends on ox_lib for its UI, context menus, and helper functions. You can’t run one without the other.

Grab the latest build from overextended/ox_lib releases. Download the ox_lib.zip from the release page — not the source code zip. The release build has the compiled web UI; the source zip doesn’t, and you’ll spend an hour confused about why nothing renders.

Extract to resources/[ox]/ox_lib (I keep all OX resources in an [ox] folder to manage start order cleanly).

Add to server.cfg:

ensure ox_lib

This has to start after oxmysql and before ox_inventory. Start order matters — it’s the single most common cause of install failures.

Step 3: Download and Install ox_inventory

Same process. Go to overextended/ox_inventory releases and download the built release, not the source. Extract to resources/[ox]/ox_inventory.

Your folder structure should now look like:

resources/
  [standalone]/
    oxmysql/
  [ox]/
    ox_lib/
    ox_inventory/

Step 4: Import the Database Schema

ox_inventory needs specific tables. Open your database and run the SQL file that ships with ox_inventory — it’s at ox_inventory/setup/convert.sql if you’re converting from another inventory, or you can just let ox_inventory auto-create its tables on first start.

For a fresh install, these are the main tables you’ll see created:

-- ox_inventory creates these automatically on startup
-- ox_inventory (for stashes and shared storage)
-- users (modified to add inventory column if missing)
-- player_inventory (for QBCore-style separation)

If you’re on ESX Legacy, the users table already has a inventory column. If you’re on QBCore, the players table has a items column. ox_inventory handles reading/writing both, but you need to make sure those columns exist as JSON or LONGTEXT fields.

Back your database up before you start the resource for the first time. Seriously:

mysqldump -u root -p your_database > backup_pre_ox_inventory.sql

If something goes wrong on first run, you restore from this and try again. Skipping this step has wiped more servers than I want to count.

Step 5: Configure server.cfg Start Order

This is where most installs break. Your start order has to be exact:

# Database first
ensure oxmysql

# ox_lib before anything using it
ensure ox_lib

# Framework next
ensure es_extended       # or qb-core, or qbx_core
ensure esx_menu_default  # any framework sub-resources

# Then ox_inventory
ensure ox_inventory

# Then everything that depends on ox_inventory
ensure your_custom_scripts

If you ensure ox_inventory before your framework, it won’t find the bridge and will throw errors like Framework not detected or attempt to index a nil value.

Step 6: Framework-Specific Setup

This is where the install diverges depending on what framework you’re running. I covered the differences between them in my ESX vs QBCore vs Qbox comparison, but here’s the install-specific part.

Qbox

Easiest scenario. ox_inventory is the native inventory for Qbox. You don’t configure a bridge — it just works. Open ox_inventory/config.lua and set:

Config.Framework = 'qbx'

Actually, in recent versions it auto-detects. You might not need to set anything. Start the server and you’re done.

QBCore

You need to tell ox_inventory you’re on QBCore and disable qb-inventory if it’s still in your server.cfg.

-- In ox_inventory/config.lua
Config.Framework = 'qb'

Remove or comment out:

# ensure qb-inventory   <-- DO NOT RUN BOTH

Every QB resource that uses qb-inventory exports directly needs to be checked. Most modern QB resources use the framework’s abstraction and work fine. Older scripts that call exports['qb-inventory']:something() need to be updated to use ox_inventory’s exports or routed through a compatibility shim.

ESX Legacy

Set the framework in config:

Config.Framework = 'esx'

You also need to make sure you’re on ESX Legacy, not the old ESX 1.2. The old version won’t work with ox_inventory without heavy patching. If you’re still on ESX 1.2 in 2026, migrating to Legacy first is a bigger priority than your inventory choice.

Most ESX resources that add or remove items use xPlayer.addInventoryItem() which ox_inventory overrides automatically. You shouldn’t need to rewrite most of your scripts — but test each one before declaring victory.

Step 7: First Startup and Smoke Test

Restart your server. Watch the console for errors.

A clean start looks like:

[     script:ox_inventory] Module loaded: db
[     script:ox_inventory] Module loaded: items
[     script:ox_inventory] Module loaded: shops
[     script:ox_inventory] Module loaded: inventory

Connect to your server and press Tab. Your inventory should open with ox_inventory’s grid UI. If you see the old QB or ESX inventory, your old inventory resource is still running. Stop it.

Test these things before trusting the install:

Pick up an item from the ground — does it go into your inventory?
Open a trunk — does the vehicle storage work?
Drop an item — does it persist if you relog?
Open a shop — does buying work?
Give an item to another player — does trading work?

If any of those fail, something’s wrong with your migration or config. Don’t leave it for later. Fix it now.

Common Errors and How to Fix Them

These are the errors I see come up over and over in support channels.

”Framework not detected”

Your framework is starting after ox_inventory. Fix your start order in server.cfg.

”attempt to index a nil value (global ‘exports’)”

ox_lib isn’t loaded or isn’t loaded before ox_inventory. Check start order and confirm ox_lib actually started (look for its startup message in console).

”SQL error: table ‘ox_inventory’ doesn’t exist”

Database wasn’t migrated. Either ox_inventory couldn’t auto-create tables (permissions issue) or you need to manually import the schema from the setup/ folder.

Items show up as “unknown item”

You’re using items from your old inventory that aren’t defined in ox_inventory’s items list. Open ox_inventory/data/items.lua and add the missing items. You can also import your old items in bulk — there are community scripts that convert QBCore’s shared items and ESX’s items table into ox_inventory format.

UI doesn’t render, just a blank screen

You downloaded the source zip instead of the release build. The source doesn’t include the compiled web UI. Delete and download the correct release from GitHub.

Server freezes for 5-10 seconds on startup

Usually a database issue — ox_inventory is trying to run migrations on a massive users or players table. On small servers this is instant, on servers with 100k+ player records it can take a minute. Let it finish, don’t kill the process.

Adding Custom Items

Once it’s running, you’ll want to add items specific to your server. Open ox_inventory/data/items.lua. Items look like this:

['bodybag'] = {
    label = 'Body Bag',
    weight = 1500,
    stack = false,
    close = true,
    description = 'Used for storing bodies',
    client = {
        image = 'bodybag.png',
    }
},

Drop the item’s PNG into ox_inventory/web/images/. The filename has to match what’s in the image field.

If you’re using scripts like our LMX Bodybag or LMX Trap & Stores, the items needed are documented in each script’s readme. Most YBN scripts ship with an items.lua snippet you can copy-paste into ox_inventory’s items file.

Configuring Shops and Stashes

ox_inventory’s shop system is defined in data/shops.lua. A basic shop:

General = {
    name = 'General Store',
    inventory = {
        { name = 'water', price = 5 },
        { name = 'bread', price = 10 },
        { name = 'phone', price = 150 },
    },
    locations = {
        vec3(25.7, -1347.3, 29.49),
        vec3(-3038.71, 585.9, 7.9),
    },
    blip = {
        id = 52,
        colour = 2,
        scale = 0.8,
    }
},

Stashes work similarly — defined in data/stashes.lua with location, weight/slot limits, and owner constraints. If you want server-wide shared stashes (like faction lockers), you define them once. For personal player stashes, you register them dynamically via exports.

Performance Tuning

ox_inventory is lightweight by default, but there are a few config options worth knowing about on a larger server. Watch your resource monitor — I covered how in the resmon optimization guide — and tune these if you see issues:

Config.Save = 10 * 60         -- save interval in seconds
Config.PlayerSlots = 50       -- default player slots
Config.DefaultWeight = 30000  -- default weight in grams
Config.BulkStashSave = true   -- batch stash saves to reduce DB load

On a 200-player server, turning on BulkStashSave cut my MySQL write load by about 40%. Your mileage will vary depending on how active your stash usage is.

Migrating From an Existing Inventory

If you’re switching from qb-inventory or ESX’s default inventory, the community has built conversion scripts. The ox_inventory setup/ folder has SQL files for common migrations, and there are GitHub repos dedicated to QBCore-to-ox conversion.

The migration process usually looks like:

Back up your database (again, non-negotiable)
Run the appropriate convert SQL file on your database
Map your old items to ox_inventory’s items.lua format
Stop the old inventory resource
Start ox_inventory
Have players log in and verify their items are intact

Expect a few items to not convert cleanly — especially anything with custom metadata. Budget time to patch these manually. Don’t do the migration on a Friday night. Do it during low-traffic hours and announce maintenance in your Discord.

Where to Go From Here

Once ox_inventory is running, you’ve got the foundation for everything else. Drug systems, crafting, jobs, shops, evidence lockers — it all builds on top of your inventory’s item and metadata system. Scripts like LMX StoreMaster and LMX Advanced Drug Sales are built specifically to integrate with ox_inventory’s exports and metadata, so you’re set up to use them immediately.

If you want to build your own scripts that interact with ox_inventory, start with the Lua scripting tutorial and then read the ox_inventory docs on exports. The API is well-documented and consistent — once you’ve used it on one project, you know how to use it on every project.

Check out our free scripts collection for add-ons and utilities that work with ox_inventory out of the box. If you hit a wall during install or have framework-specific weirdness to sort out, drop into our Discord — someone’s probably already solved the exact issue you’re running into.