QBCore is not a framework you drop into a resources folder and walk away from. It has a real dependency chain: a database has to exist before the framework can create characters, and one specific resource has to be running before QBCore itself will even start cleanly. Get that order wrong and you will spend an evening staring at console errors that all trace back to the same root cause.

Short answer:installing QBCore means setting up MariaDB and oxmysql first, since qb-core formally depends on oxmysql and imports its MySQL library directly in its resource manifest. From there you clone or download qbcore-framework/qb-core into your resources folder, import its qbcore.sql file into your database, and make sure server.cfg starts oxmysql before qb-core. txAdmin's Recipe Deployer can automate most of this through its built-in QBCore template.

What qb-core is, and why the install order matters

A framework core, not a standalone gamemode

The qb-core repository describes itself simply as the core resource for the framework, containing all of the core functionality and features. It is licensed GPL-3.0 and its license header credits ESX (Jérémie N'gadi) and Joshua Eger for work dating back to 2015, which places QBCore in the same lineage as ESX rather than as an unrelated competitor.

The oxmysql dependency is not optional

This is the detail most install guides skim past. qb-core's own resource manifest lists dependency 'oxmysql' explicitly, and its server scripts import @oxmysql/lib/MySQL.luadirectly, ahead of qb-core's own server files. That is not a suggestion to install oxmysql at some point. It means qb-core is written assuming oxmysql's library already exists in memory when it starts. If oxmysql is missing or starts after qb-core in server.cfg, qb-core has nothing to import and fails immediately.

Prerequisites before you install anything

  • The FiveM server artifacts for your operating system, extracted and able to run FXServer.exe (Windows) or run.sh (Linux).
  • A free Cfx.re license key, generated at keymaster.fivem.net.
  • MariaDB installed, since oxmysql needs an actual MySQL-compatible server to connect to.
  • A database client to run SQL imports, such as HeidiSQL on Windows or the mysql command line on Linux.

Step 1: get your artifacts and license key

Download the latest recommended server build for your platform, extract it, and run it once so you can generate and confirm your license key. A Keymaster key only checks the IP address on its first launch; after that, the same key works from any IP, which matters if you move the server to different hardware later.

The steps differ slightly by platform. On Windows, this means extracting the artifact archive and running FXServer.exe directly. On Linux, it means downloading the matching Linux artifact, then extracting it with a command such as tar -xf fx.tar.xz and launching it with ./run.sh. Linux installs also typically install MariaDB through the system package manager rather than a standalone installer, and if you need the database reachable from a separate application server, that means editing the bind address in MariaDB's configuration and opening the database port in your firewall, on top of the steps below.

Step 2: set up MariaDB and oxmysql

Install MariaDB and create a database plus a dedicated database user for your server, rather than connecting as root. Then download the latest oxmysql release and extract it into your resources folder. Two things matter here:

  • Place oxmysql at the top of your resource list in server.cfg, before anything that depends on a database connection.
  • Set the mysql_connection_string convar in a format such as mysql://user:password@localhost:3306/qbcore, or the equivalent semicolon-separated form. Avoid characters like ; , / ? : @ & = + $ # in your username or password, since they can conflict with the connection string format itself.

Two optional convars are worth setting while you are in there: mysql_slow_query_warning flags queries slower than a threshold you choose, and mysql_debug true logs every query, which is useful while you are still debugging a fresh install and should be turned off again afterward.

Step 3: clone qb-core and import its database

Inside your resources folder, run:

git clone https://github.com/qbcore-framework/qb-core.git

If you would rather not use git, GitHub's repository page also offers a plain ZIP download that extracts the same way. Either method gives you the same files, including qbcore.sql at the repository root. Import that file into the database you created in Step 2 using HeidiSQL or the mysql command line. Skipping this step is a common cause of installs that boot but cannot create a character on first join, since the tables QBCore expects simply do not exist yet.

Step 4: configure config.lua

qb-core's config.lua is where server identity and economy defaults live. A few fields worth understanding before your first launch:

  • Config.MaxPlayers reads your server's sv_maxclients convar directly, defaulting to 48 if it is not set.
  • Config.DefaultSpawn is the vector4 coordinate new characters spawn at.
  • Config.Money.MoneyTypes defines starting cash, bank, and crypto balances for new characters. Changing these later does not remove balances already granted to existing players.
  • Config.Server.Whitelist and Config.Server.WhitelistPermission gate the server behind an ACE permission group, 'admin' by default.
  • Config.Server.Permissions lists the permission groups QBCore expects to exist, which you still have to grant to real identifiers in server.cfg with add_ace.
  • Config.Player.HungerRate and Config.Player.ThirstRate control how quickly a character's needs decay, and Config.Money.PayCheckTimeOut sets how often a paycheck is issued in minutes. None of these need to change for a working first boot, but they are the first knobs most owners touch once real players are on the server.

At the time of writing, qb-core's own resource manifest reports itself as version 1.3.0. Framework versions move quickly, so treat that as a snapshot rather than a number to chase; the dependency and file structure described here has been stable across recent releases.

Step 5: server.cfg ensure order

Given the dependency declared in qb-core's own manifest, the order in server.cfg is not cosmetic:

  1. Set mysql_connection_string, then ensure oxmysql.
  2. ensure qb-core.
  3. Any companion resources you add afterward, such as multicharacter, spawn selection, inventory, or job scripts, since they depend on qb-core already being loaded.

Recall from the official server commands reference: ensure restarts a resource if it is already running, or starts it if it was not. That makes it the right choice for this list, since it behaves predictably whether you are starting fresh or reloading after a config change.

Step 6: first boot, what to expect

On a clean start, watch the console for oxmysql confirming its database connection before qb-core initializes. qb-core itself only provides the framework core, it does not include a character-creation screen, spawn selection menu, or inventory UI on its own. Those come from separate companion resources installed after qb-core, which is why a bare qb-core install alone will not yet give you a playable character on first join.

A QBCore server that boots without errors and a QBCore server that can actually create a character are two different milestones. The gap between them is almost always a missing SQL import or a resource that started before its dependency.

The faster path: letting txAdmin do this for you

Everything above is the manual path, useful for understanding what is actually happening and for diagnosing errors later. txAdmin's Recipe Deployer can do most of it for you: its Popular Recipes list includes a QBCore template that downloads qb-core and its standard companion resources, prompts you for database credentials during deploy, runs the SQL imports automatically, and writes server.cfg with the correct resource order already in place. If your goal is a working server rather than understanding every step, deploying the QBCore recipe through txAdmin's setup wizard gets you there with far fewer manual steps than cloning and wiring everything up by hand.

Common QBCore installation errors and how to fix them

  • qb-core errors immediately on start. Check that oxmysql appears above qb-corein server.cfg and is actually starting, not just present in the resources folder. qb-core's manifest declares oxmysql as a hard dependency, so a missing or late-starting oxmysql breaks it.
  • Connection string fails silently. A database password containing reserved characters such as ; , / ? : @ & = + $ # can break the connection string format. Use a plain alphanumeric password, or switch to the semicolon key-value connection format instead of the URI format.
  • Server boots but characters will not create. This almost always means qbcore.sql was never imported into the database your connection string points to. Reimport it and confirm the database name in HeidiSQL or the mysql client matches your connection string exactly.
  • Locked out after enabling whitelist. Grant your own identifier the ACE group referenced by Config.Server.WhitelistPermission in server.cfg before enabling Config.Server.Whitelist, not after.
  • First boot hangs or seems stuck. Let dependency installation finish completely on first launch rather than restarting midway; interrupting it before it completes is a documented cause of broken first installs.

Where self-install stops being enough

Getting a QBCore server to boot is a solved problem once you know the dependency order. What this guide does not cover is whether the third-party jobs, vehicles, and inventory scripts you add on top of QBCore are actually compatible with each other, or whether your server.cfg is tuned for the player count you are targeting. That is a different kind of testing than a clean install checklist can give you.

If you want your framework choice and script stack reviewed before you add real content, our framework fit guide covers how QBCore compares to Qbox and ESX for a 2026 build, and a scoped build engagement can cover configuration and compatibility testing beyond the install itself.

The bottom line on installing QBCore

QBCore's install steps are not complicated in isolation. Database, then oxmysql, then qb-core, then everything else. Where first installs actually fail is skipping the SQL import, starting resources out of order, or flipping on the whitelist before granting the matching ACE group. Follow the dependency chain qb-core itself declares, and the rest of the install is mostly waiting for downloads to finish.