How to Install QBCore on Your FiveM Server (Step-by-Step)

QBCore has become the most widely recommended FiveM framework for new servers in 2025. It features a clean, modern Lua codebase, is actively maintained by an experienced team, and has a rapidly growing ecosystem of compatible scripts. This guide walks you through installing it correctly from scratch on a fresh server.

Prerequisites

Before starting, make sure you have:

• A running FiveM server with server artifacts installed
• MySQL installed and a database already created
• oxmysql installed and configured as your database connector
• ox_lib downloaded (ox_inventory depends on it)
• Git installed on your server for easy resource downloading

If you do not have these yet, read our MySQL setup guide and FiveM server setup guide first.

---

Step 1: Download the QBCore Resources

QBCore is split across multiple repositories under the QBCore-Framework GitHub organization. At minimum, you need these resources:

• qb-core — the framework core itself
• qb-multicharacter — character selection screen
• qb-spawn — spawn point selection
• qb-hud — player HUD (health, armor, hunger, money)
• qb-menu — UI menu system used by most scripts
• qb-input — input dialog system
• qb-notify — notification system

Clone each one into your resources folder. It is best practice to organize framework files in a subfolder:

git clone https://github.com/qbcore-framework/qb-core resources/[qb]/qb-core
git clone https://github.com/qbcore-framework/qb-multicharacter resources/[qb]/qb-multicharacter
git clone https://github.com/qbcore-framework/qb-spawn resources/[qb]/qb-spawn
git clone https://github.com/qbcore-framework/qb-hud resources/[qb]/qb-hud
git clone https://github.com/qbcore-framework/qb-menu resources/[qb]/qb-menu
git clone https://github.com/qbcore-framework/qb-input resources/[qb]/qb-input
git clone https://github.com/qbcore-framework/qb-notify resources/[qb]/qb-notify

---

Step 2: Import the QBCore SQL File

QBCore requires several database tables to store player data, characters, job assignments, and more. The SQL file is located inside the qb-core resource folder.

Using the command line:

mysql -u root -p your_database_name < resources/[qb]/qb-core/qb-core.sql

Using HeidiSQL:

1. Open HeidiSQL and connect to your MySQL server
2. Select your FiveM database in the left panel
3. Go to File → Run SQL File
4. Select qb-core.sql and click Open
5. Confirm there are no red errors in the output panel

---

Step 3: Configure oxmysql

oxmysql must start before QBCore. Make sure your server.cfg connection string is correct and positioned before the ensure lines:

set oxmysql_connection_string "mysql://username:password@localhost/database_name?charset=utf8mb4"

ensure oxmysql
ensure qb-core

---

Step 4: Add All Resources to server.cfg

Load order is critical. The list below shows the correct sequence:

ensure oxmysql

ensure qb-core

ensure qb-multicharacter
ensure qb-spawn
ensure qb-hud
ensure qb-menu
ensure qb-input
ensure qb-notify

All scripts that depend on qb-core must be listed below these lines in your server.cfg.

---

Step 5: Register Items in the Items Config

QBCore stores all item definitions in qb-core/shared/items.lua. Every item that any script uses must be registered here. A typical item entry looks like:

['water'] = {
    name        = 'water',
    label       = 'Water',
    weight      = 500,
    type        = 'item',
    image       = 'water.png',
    unique      = false,
    useable     = true,
    shouldClose = true,
    description = 'A bottle of water'
},

When you install a new script that adds items, check its documentation for the item definitions to add here. A script that references an item not registered in this file will fail at runtime.

---

Step 6: Configure Jobs

Jobs are defined in qb-core/shared/jobs.lua. Add every job your server will use before launching. A typical job entry:

['police'] = {
    label       = 'Law Enforcement',
    defaultDuty = true,
    offDutyPay  = false,
    grades      = {
        ['0'] = { name = 'Cadet',      payment = 50  },
        ['1'] = { name = 'Officer',    payment = 75  },
        ['2'] = { name = 'Sergeant',   payment = 100 },
        ['3'] = { name = 'Lieutenant', payment = 125 },
        ['4'] = { name = 'Chief', isboss = true, payment = 150 },
    },
},

Scripts that reference a job name not defined here will throw errors on startup.

---

Step 7: Start the Server and Read the Console

Start your server and watch the console output carefully. A successful QBCore startup looks like:

[qb-core] QBCore Loaded!
[qb-core] Connected to database!
[qb-multicharacter] Started
[qb-spawn] Started

Common errors and their causes:

| Error | Cause | |---|---| | Database connection failed | Wrong credentials or database name in connection string | | Table 'players' doesn't exist | SQL file was not imported | | attempt to index a nil value (QBCore) | A script is loading before qb-core — fix load order |

---

Step 8: Connect and Verify

Join your local server and confirm:

• The character creation screen appears correctly
• You can create a character and spawn into the world
• The HUD is visible with health, armor, and money bars
• Pressing F8 shows no red errors in the client console

From here you can begin adding job scripts, inventory, housing, vehicles, and all the content that makes your server unique.

---

Looking for QBCore-compatible scripts with clear documentation? Every listing on ModForge states framework compatibility upfront. Browse at modforge.xyz.