If you have dropped more than a handful of scripts into a FiveM server, you have almost certainly seen a resource refuse to start with a message like “Failed to load script — attempted to call a nil value” or a flat dependency warning in the console. Nine times out of ten the culprit is the same: ox_lib is either missing or starting in the wrong order. This guide explains what ox_lib actually is, why so many scripts depend on it, how to install it correctly, and how to use its most commonly needed features.
What Is ox_lib?
ox_lib is an open-source FiveM (and RedM) resource maintained by the Overextended community at github.com/overextended/ox_lib. Its own description is concise: “a comprehensive FiveM development library that streamlines resource creation through shared utilities, UI components, and common framework abstractions.” In practical terms it is a single resource that ships a standardised set of tools — UI widgets, a client-server callback system, cache helpers, locale support, and more — so that every script on your server can use the same polished components instead of each bundling its own.
ox_lib is framework-agnostic. It works alongside ESX, QBCore, QBOX, and standalone servers. It is not a framework itself; think of it as the standard library that sits below your framework and scripts.
Why So Many Scripts Depend on It
Before ox_lib became the de-facto standard, every script author wrote their own notification pop-up, their own progress bar, their own callback wrapper. Players ended up staring at five different notification styles on one server, and server owners spent hours debugging callback timing bugs that each script solved differently. ox_lib solved that by giving the community one well-tested implementation of each feature.
When a resource declares dependency 'ox_lib' in its fxmanifest.lua, it is signalling that it offloads all of that boilerplate to ox_lib. Remove ox_lib (or start it after the dependent resource), and the dependent resource’s calls into the lib global land on a nil table — instant crash on load. This is the most common source of resource load failures on servers running modern paid or community scripts.
Core Modules at a Glance
ox_lib uses a lazy-loading pattern: modules are pulled in from imports/{module}/{context}.lua only when first accessed through the lib global. That keeps startup overhead low. The table below lists the modules you will encounter most often.
| Module | Side | What it provides |
|---|---|---|
| notify | Client | Toast-style notifications (lib.notify) |
| context | Client | Themed popup context menus (lib.registerContext / lib.showContext) |
| callback | Client + Server | Typed client↔server callbacks (lib.callback) |
| progressBar | Client | Cancellable action progress bars (lib.progressBar) |
| inputDialog | Client | Form-style input dialogs (lib.inputDialog) |
| cache | Shared | Reactive cache for ped, vehicle, seat, etc. |
| locale | Shared | Localisation string loading (lib.locale) |
| table / math | Shared | Extended table and math helpers |
Installing ox_lib
Always install from the compiled release — not raw source. The release zip contains the pre-built NUI (web UI) assets that the source tree does not include.
- Download the latest release zip from the ox_lib releases page. The direct link to the latest build is:
https://github.com/overextended/ox_lib/releases/latest/download/ox_lib.zip - Extract the zip. You will get a folder named
ox_lib. - Upload that folder into your server’s
resources/directory (or a sub-category such asresources/[ox]/). - Add the ensure line to
server.cfg— see the section below for the correct position.
ox_lib’s own fxmanifest.lua declares fx_version 'cerulean' and requires a minimum server build of /server:7290 and /onesync. If your server artifact is older than build 7290 or OneSync is disabled, ox_lib will refuse to start. Check your artifact version in the txAdmin dashboard or the server console on startup.
server.cfg: The Ensure Order That Matters
FiveM starts resources in the order they appear in server.cfg. The dependency field in a resource’s manifest acts as a safety net that prevents a resource from starting before its declared dependencies — but only if those dependencies are already being started by an ensure line. If ox_lib is not ensured at all, the dependency check still fails. Order and presence both matter.
The correct sequence for the Overextended stack is:
# Database layer first
ensure oxmysql
# Shared library next — everything else can depend on this
ensure ox_lib
# Your framework
ensure es_extended
# or: ensure qb-core
# Interaction / inventory after the library and framework are up
ensure ox_target
ensure ox_inventory
# Your game scripts below this line
ensure my_custom_job
ensure my_garage_scriptIf you place ensure ox_lib after ensure my_custom_job, the job script will start first, call into the lib global (which does not exist yet), and crash. This is the single most common ox_lib installation mistake.
Declaring the Dependency in fxmanifest.lua
There are two things you need in the fxmanifest.lua of any resource that uses ox_lib: the shared script import and the dependency declaration.
fx_version 'cerulean'
game 'gta5'
shared_script '@ox_lib/init.lua'
dependencies {
'ox_lib',
}
-- your other scripts below
client_script 'client.lua'
server_script 'server.lua'The shared_script '@ox_lib/init.lua' line instructs FiveM to load ox_lib’s initialisation file into your resource’s runtime on both client and server. This is what creates the lib global that all subsequent calls rely on. The dependencies { 'ox_lib' } block tells the server to refuse to start your resource if ox_lib is not running — it is your in-manifest failsafe on top of the server.cfg order.
If you only want specific modules loaded (for example, only locale and table helpers), some resources use an ox_libs table to opt in to individual modules rather than loading everything. You will see this pattern in ox_inventory’s own manifest. For most server owners running pre-built scripts you do not need to worry about this — the script’s own manifest handles it.
Using the Key Features
Notifications
Call lib.notify from any client-side script to display a toast notification. The type field controls colour and icon — accepted values are success, error, info, and warning.
-- Client-side example
lib.notify({
title = 'Garage',
description = 'Vehicle spawned successfully.',
type = 'success',
duration = 4000,
})Context Menus
Context menus are registered once with lib.registerContext and opened with lib.showContext. A common pitfall: if you define the options list as a keyed Lua table rather than an array, ox_lib sorts them alphabetically. Use an array table (numeric indices) to preserve the order you intend.
-- Client-side example
lib.registerContext({
id = 'garage_menu',
title = 'Personal Garage',
options = {
{
title = 'Retrieve Vehicle',
description = 'Spawn your last saved car.',
event = 'garage:retrieveVehicle',
},
{
title = 'Store Vehicle',
description = 'Save the vehicle you are currently in.',
event = 'garage:storeVehicle',
},
},
})
lib.showContext('garage_menu')Callbacks
ox_lib’s callback system lets a client script ask the server for data and receive the result asynchronously. Register the handler on the server, call it from the client.
-- Server-side: register the callback
lib.callback.register('myScript:getPlayerMoney', function(source)
local player = GetPlayerIdentifier(source, 0)
return 1500 -- return value(s) sent back to client
end)
-- Client-side: call the callback
lib.callback('myScript:getPlayerMoney', false, function(money)
lib.notify({ title = 'Balance', description = '$' .. money, type = 'info' })
end)The second argument to lib.callback on the client side is the optional data payload to send to the server. Pass false if you have nothing to send.
ox_lib, ox_target, and oxmysql — How They Fit Together
These three resources come from the same Overextended organisation and are designed to complement each other, but they are independent. oxmysql is a MySQL wrapper for FXServer — it handles all database queries. ox_lib is the UI and utility layer. ox_target is a standalone “third-eye” interaction resource that lets players point at objects or peds to see context options. A script can use any combination; using ox_target does not require ox_lib, and vice versa — but since many scripts depend on ox_lib, it effectively ends up at the base of most stacks.
If you are building out a full server and want a deeper look at the targeting system, see the ox_target setup guide for step-by-step configuration. For common resource loading failures caused by incorrect start order, the FiveM resource loading errors troubleshooting guide covers the most frequent patterns.
Official documentation for all three resources (along with ox_inventory and ox_core) lives at overextended.dev. The community previously maintained a mirror at coxdocs.dev, which now redirects to the same domain. When in doubt, the canonical source is always the official site or the GitHub repository.
Getting ox_lib Running on a Managed Server
If you are managing your own FiveM RP server environment rather than self-hosting on bare metal, the installation process is the same — upload the ox_lib folder to your resources directory, edit server.cfg via the file manager or txAdmin, and restart the server. The panel’s console output will immediately show whether ox_lib started cleanly or threw a dependency error. Our FiveM server documentation also covers common first-time setup steps.
Frequently Asked Questions
Do I need ox_lib if I am running a QBCore or ESX server?
Neither QBCore nor ESX requires ox_lib as a hard dependency by default, but the majority of actively developed community and commercial scripts now depend on it. If you install even one such script and ox_lib is absent, that script will fail to start. It is practical to treat ox_lib as a baseline resource on any modern FiveM server regardless of framework.
My resource still crashes even though ox_lib is ensured. What should I check?
First, confirm that ensure ox_lib appears in server.cfg before the crashing resource — not just before end-of-file. Second, verify the resource’s fxmanifest.lua contains both shared_script '@ox_lib/init.lua' and dependency 'ox_lib' (or dependencies { 'ox_lib' }). Third, check that your server build meets the minimum requirement: build 7290 or higher with OneSync enabled. Any one of these three missing pieces produces the same “nil value” crash.
Should I install from the GitHub source code or the release zip?
Always use the release zip from the releases page. The source code on the master branch does not include the pre-compiled NUI web assets (web/build/index.html and associated files) that the context menus, notifications, and other UI components depend on. Cloning the source and placing it directly in your resources folder will result in a broken or invisible UI even if the Lua layer starts without errors.
Ready to play?
Run your own FiveM server with XGamingServer
Spin up an always-on FiveM server your friends can join in minutes — no port-forwarding, no tech headaches.
