How to Install a FiveM Script on QBCore, QBox or ESX (Step by Step)

Most "this script does not work" messages have nothing to do with the script. A folder has the wrong name, a dependency starts too late, an SQL file was never run, or an item was never added to the inventory. The good news: these are easy to check once you know the order.

This guide walks through installing a FiveM script on QBCore, QBox or ESX, from the download to a clean server console. It applies to our scripts and to most others. Always read the script’s own readme too; it wins over any general guide.

Before you start

• Use a test server. Install on a copy of your server first. A broken install on a live server with players can corrupt characters or inventories.
• Back up your database. Especially before running SQL files.
• Know your stack. Which framework (QBCore, QBox, ESX), which inventory, which target system. The script’s readme will ask.
• Update the basics. Old versions of oxmysql, ox_lib or your framework cause more errors than anything else.

Step 1: Download and unzip

Download the script from wherever you bought it. With our scripts, that is your account on this site. Unzip it on your PC. Don’t put the zip file itself into the resources folder; FiveM can’t read it.

Step 2: Check the folder name

The folder name is the resource name. It matters, because other resources and your server.cfg refer to it.

• Remove suffixes such as -main or -master that GitHub downloads add.
• Don’t rename a resource if its readme says the name must stay, since some scripts check it.
• The folder must contain fxmanifest.lua directly, not inside another folder. If you open the folder and see a second folder with the same name, move that inner one up.

Step 3: Put it in your resources

Copy the folder into your server’s resources directory. Many servers sort resources into bracket folders, such as [jobs] or [addons]. FiveM treats folders in square brackets as categories, and scans them for resources.

Step 4: Read the dependencies

Open the readme and fxmanifest.lua. Look for:

• dependencies: resources that must be running first, such as ox_lib, oxmysql, your framework or a target system,
• optional integrations: resources the script uses if they are present,
• framework notes: which frameworks are supported and how.

Our product pages list the required and optional resources under "What you need", so you can check this before you buy.

Step 5: Run the SQL (if there is any)

Some scripts store data in the database and ship an .sql file. Run it once in your database tool (HeidiSQL, phpMyAdmin or your host’s panel), on the same database your server uses.

• Run it once. Running it twice may create duplicate tables or rows.
• Read error messages. "Table already exists" usually means it was run before.
• Some scripts create their tables automatically on first start. The readme will say.

Step 6: Add items, if the script uses them

This step differs most between frameworks.

QBCore

With qb-inventory, items are usually defined in qb-core/shared/items.lua. Add the script’s items there, in the same format as the existing ones. Copy the item images into your inventory’s image folder.

QBox

QBox servers usually run ox_inventory. Items go into ox_inventory/data/items.lua, and images into ox_inventory’s image folder. Follow the ox_inventory format, which differs from the QBCore one.

ESX

ESX Legacy without ox_inventory stores items in the items table in the database, so the script’s SQL often includes them. With ox_inventory, use ox_inventory/data/items.lua as above.

Item changes usually need a full server restart, not just a resource restart.

Step 7: Add it to server.cfg

Add an ensure line after everything the script depends on:

ensure oxmysql
ensure ox_lib
ensure qb-core

ensure ox_target
ensure ox_inventory

ensure your_new_script

On QBox use qbx_core, on ESX es_extended, in place of qb-core. If the script is inside a bracket folder that you already ensure, you do not need a separate line. Just make sure that folder starts after the dependencies.

Load order is the most common cause of errors like "attempt to index a nil value" at start-up: the script tried to use something that was not running yet.

Step 8: Configure

Open config.lua (or the files the readme mentions) and set:

• your framework, if the script supports several,
• your inventory, target and notification resources,
• locations, prices, job names and permissions.

Change one thing at a time and keep a copy of the original file. When you update the script later, you will want to compare your config with the new default.

Step 9: Start and check both consoles

Restart the server and watch:

• the server console (or txAdmin’s live console) for red lines when the resource starts,
• the client console (F8 in game) for errors when you use the script.

The first red line is usually the real problem. Everything after it is often a consequence.

Common errors and what they mean

What you see	Usual cause
Couldn’t find resource	Wrong folder name, or fxmanifest.lua is one folder too deep
Attempt to index a nil value at start	A dependency is missing or starts after the script
No such export	The resource that provides the export is not running, or is an incompatible version
Unknown column or table	The SQL file was not run, or was run on another database
Item shows without image or name	Item not added to the inventory, or image missing
Works for you, not for players	Permissions, job names or ACE settings in the config

Step 10: Test like a player

Log in with a normal character, not an admin. Use every feature once: buy, sell, start the job, open the menu. Check that nothing appears for players who should not see it.

Then check performance with the resource monitor. FiveM resmon basics explains the numbers.

Updating a script later

1. Read the changelog for the new version. Breaking changes should be listed first.
2. Back up your current folder, especially the config.
3. Replace the files, then compare your old config with the new default one. Renamed keys are the usual cause of problems after an update.
4. Run any new SQL the changelog mentions.
5. Restart and check both consoles again.

With full-source scripts you can also diff your edited files against the new version. That is much harder with escrowed code. See escrow vs open source FiveM scripts.

When to ask for help

If you have followed every step and still see an error, contact the script’s support with:

• the script name and version,
• your framework and its version,
• your server artifact version,
• the exact red lines from the server and client console,
• what you changed recently.

For our scripts, our support page has a ready-made template. Send the console output, not a photo of your screen.

Where to go next

If you are building a server from scratch, start with the QBCore and QBox setup guide. For a GTA 6 (GTA VI) inspired look, see the Vice City checklist.

Browse our FiveM scripts by framework: QBCore scripts, QBox scripts and ESX scripts. The free scripts, such as the FiveM loading screen and the FiveM robbery script, are a good way to practise an install, and bundles group scripts that work together.