Installer ox_lib sur un serveur FiveM : la bibliothèque indispensable pour le scripting moderne

Ouvrez le dossier resources d'un serveur FiveM monté en 2026 et comptez les scripts qui démarrent par shared_script '@ox_lib/init.lua' : inventaires, téléphones, garages, systèmes de métiers, presque tout le catalogue moderne s'appuie sur ox_lib, la bibliothèque utilitaire publiée par Overextended. Elle fournit aux scripts Lua et JavaScript ce que les frameworks ne standardisent pas : notifications, prompts à l'écran, menus contextuels, boîtes de saisie, barres de progression, callbacks client-serveur, traductions. Ce guide s'adresse à la personne qui administre le serveur, chez un hébergeur ou sur un VPS qu'elle gère elle-même : installation de la dernière version d'ox_lib et de sa nouvelle dépendance cfxlua-require, configuration dans server.cfg, premier script qui affiche une notification, un prompt et un menu, place d'ox_lib à côté d'ESX, de QBCore et de Qbox, et lecture des erreurs de dépendances qui remplissent la console txAdmin. Si votre serveur n'est pas encore en ligne, commencez par notre guide de mise en place d'un serveur FiveM.

ox_lib, la bibliothèque de l'écosystème Overextended

ox_lib est une ressource FiveM publiée sous licence LGPL-3.0 sur GitHub et documentée sur overextended.dev. Ce n'est pas un framework : elle ne gère ni comptes, ni métiers, ni inventaire. C'est une bibliothèque de fonctions partagées, chargée une seule fois sur le serveur, que chaque script appelle à travers la table globale lib. Une ressource qui veut afficher une notification n'embarque plus sa propre page NUI : elle appelle lib.notify, et c'est l'interface d'ox_lib, commune à tout le serveur, qui l'affiche. Même logique pour les menus, les dialogues, la progression d'une action ou la vérification de version d'une ressource. Le code se divise en deux parties : le dossier imports, chargé dans chaque script qui déclare ox_lib, et le dossier resource, exécuté par ox_lib lui-même. Une version JavaScript existe sous forme de paquet npm, @overextended/ox_lib, avec une couverture partielle des fonctions Lua.

Le rythme de publication est soutenu : la version 3.42.1 est sortie le 3 novembre 2026, deux jours après la 3.42.0, elle-même précédée de la 3.41.0 du 25 octobre et de la 3.40.3 du 15 octobre. Deux changements récents comptent pour l'administration d'un serveur. Depuis la 3.41.0, le système de modules require vit dans un projet séparé, cfxlua-require, livré dans l'archive de release à côté d'ox_lib ; les notes de version expliquent que cette séparation évite les conflits entre bibliothèques qui redéfinissent chacune leur require, ESX étant cité en exemple. Depuis la 3.42.0, un module de versionnage sémantique vérifie au démarrage que les dépendances d'ox_lib sont à la version attendue, cfxlua-require 1.0.2 au minimum. Un mot enfin sur le fork CommunityOx/ox_lib que vous croiserez encore dans des tutos plus anciens : son dépôt GitHub est archivé en lecture seule depuis le 28 avril 2026. Installez la version Overextended.

Prérequis côté serveur

• Un serveur FiveM (FXServer) dont les artefacts sont au moins à la version 7290 : c'est la contrainte /server:7290 inscrite dans le manifeste d'ox_lib. Les frameworks récents demandent plus, Qbox exige par exemple la version 10731. Si votre serveur tourne sur des artefacts anciens, notre guide pour configurer la version des artefacts explique la mise à jour.
• OneSync activé (convar onesync à on), deuxième contrainte du manifeste. Sans OneSync, FXServer refuse de démarrer ox_lib.
• Lua 5.4 : tous les scripts Lua de FiveM s'exécutent en 5.4 depuis juin 2025 et la directive lua54 'yes' est dépréciée, mais elle reste présente dans la plupart des manifestes, y compris celui d'ox_lib, sans effet négatif.
• Un accès aux fichiers du serveur (panel de l'hébergeur, client SFTP, ou terminal sur un VPS Linux) et à la console txAdmin. Sur nos offres serveur FiveM, txAdmin et la protection anti-DDoS sont inclus et le répertoire resources est accessible depuis le panel.
• Pas de base de données : ox_lib n'utilise pas MySQL. En revanche, la plupart des scripts qui dépendent d'ox_lib dépendent aussi d'oxmysql ; voyez notre guide pour lier une base de données MySQL à un serveur FiveM.

Installer ox_lib et cfxlua-require

Téléchargez l'archive ox_lib.zip depuis la dernière release GitHub, jamais le bouton « Code » du dépôt : un clone des sources ne contient pas l'interface compilée (web/build) ni cfxlua-require, et ox_lib démarre alors sans aucune interface, ou ne démarre pas du tout. L'archive contient deux dossiers frères : ox_lib et cfxlua-require. Déposez les deux dans le répertoire resources de votre serveur, par exemple dans une catégorie [ox], sans renommer ni l'un ni l'autre. Le manifeste de cfxlua-require déclare provide 'require' : c'est ainsi qu'il satisfait la dépendance require inscrite dans le manifeste d'ox_lib, quel que soit le nom de son dossier.

resources/
└── [ox]/
    ├── cfxlua-require/
    │   ├── fxmanifest.lua       (provide 'require', version 1.0.2)
    │   ├── init.lua
    │   ├── LICENSE
    │   └── README.md
    └── ox_lib/
        ├── fxmanifest.lua
        ├── init.lua
        ├── require.lua
        ├── imports/
        ├── resource/
        ├── modules/
        ├── locales/             (33 langues, dont fr.json)
        └── web/build/           (interface compilée)

Sur un FXServer que vous administrez vous-même, sous Ubuntu ou Debian, les mêmes étapes se font en ligne de commande, dans un shell ouvert en SSH, depuis le compte qui lance le serveur, dans le dossier server-data qui contient server.cfg. Le seul paquet système à ajouter est unzip : ox_lib n'a pas d'installeur, ne dépend d'aucun paquet Lua, Node.js ou Python de la distribution, et les runtimes de script sont livrés avec les artefacts FXServer.

sudo apt install -y unzip
cd ~/FXServer/server-data/resources
mkdir -p '[ox]'
curl -L -o /tmp/ox_lib.zip https://github.com/overextended/ox_lib/releases/latest/download/ox_lib.zip
unzip /tmp/ox_lib.zip -d '[ox]'
ls '[ox]'              # doit lister cfxlua-require et ox_lib

Deux détails propres aux systèmes Unix évitent un ticket. Le système de fichiers distingue les majuscules : un répertoire Ox_lib n'est pas ox_lib, alors que sous Windows les deux se confondent, et un serveur migré d'un PC Windows vers un VPS Linux refuse parfois de démarrer pour cette seule raison. Ensuite, extrayez et lancez avec le même compte utilisateur, dédié au serveur, jamais en root : des dossiers créés en root appartiennent à root, et le compte qui exécute FXServer peut se retrouver sans droit d'écriture sur server-data, où le serveur écrit son cache. Les crochets du dossier [ox] sont une convention de rangement, pas une obligation : FXServer parcourt les dossiers entre crochets comme des catégories et y cherche les manifestes.

Sous Windows ou depuis le panel de l'hébergeur

FXServer existe en deux builds, Windows et Linux, publiés sur runtime.fivem.net : il n'y a pas de version macOS, donc depuis un Mac on administre toujours un serveur distant, par SSH ou par le panel de l'hébergeur. Sous Windows, l'exécutable est FXServer.exe, dans le dossier des binaires (par exemple C:\FXServer\server), et les ressources vivent dans un dossier de données séparé, C:\FXServer\server-data\resources. Pour installer ox_lib, un clic droit sur ox_lib.zip puis « Extraire tout » vers ce répertoire suffit ; en PowerShell (5.1 ou plus récent), la commande Expand-Archive fait la même chose. L'option -LiteralPath évite que les crochets du nom de dossier soient lus comme un joker.

# PowerShell, sous Windows
Set-Location C:\FXServer\server-data\resources
New-Item -ItemType Directory -Name '[ox]'
Set-Location -LiteralPath '[ox]'
Expand-Archive -LiteralPath "$env:USERPROFILE\Downloads\ox_lib.zip" -DestinationPath .
Get-ChildItem           # doit lister cfxlua-require et ox_lib

Le lancement se fait ensuite depuis une invite cmd ou PowerShell ouverte dans server-data : C:\FXServer\server\FXServer.exe +exec server.cfg démarre le serveur en lisant la config, et la même commande sans +exec lance txAdmin, qui est un composant de FXServer et n'a rien à installer. Sur un hébergement managé, rien de tout cela n'est nécessaire : sur nos offres serveur FiveM, le panel Pterodactyl fournit un gestionnaire de fichiers dans le navigateur et un accès SFTP (FileZilla, WinSCP), txAdmin est préinstallé, et vous n'avez ni exécutable à lancer ni compte root à gérer.

Configurer server.cfg : convars et ordre de démarrage

server.cfg est le fichier de configuration exécuté au boot du serveur par +exec : chaque ligne est une commande console. Ajoutez-y les lignes d'ox_lib. La seule obligatoire est ensure ox_lib, placée avant chaque script qui en dépend : ensure démarre la ressource si elle est arrêtée et la redémarre sinon. Aucune ligne n'est nécessaire pour cfxlua-require, FXServer le charge lui-même comme dépendance d'ox_lib. Les convars sont facultatives : ox:locale fixe la langue de l'interface et des scripts qui utilisent le module de traduction (le fichier fr.json est fourni), ox:userLocales à 1 laisse chaque joueur choisir sa langue avec la commande /ox_lib, ox:primaryColor et ox:primaryShade règlent la couleur d'accent des menus, et ox:progressPropLimit plafonne le nombre d'objets attachés par une barre de progression. Les quatre lignes add_ace ne servent qu'aux scripts qui ajoutent ou retirent des permissions ACE à travers les fonctions d'ox_lib ; sans elles, ces appels sont refusés par le serveur.

# server.cfg : convars ox_lib, avant la ligne ensure
setr ox:locale fr
setr ox:userLocales 1
setr ox:primaryColor blue
setr ox:primaryShade 8
setr ox:progressPropLimit 2

# facultatif : autorise ox_lib à gérer des ACE pour le compte des scripts
add_ace resource.ox_lib command.add_ace allow
add_ace resource.ox_lib command.remove_ace allow
add_ace resource.ox_lib command.add_principal allow
add_ace resource.ox_lib command.remove_principal allow

# ordre de démarrage : la bibliothèque avant tout ce qui l'utilise
ensure oxmysql
ensure ox_lib
ensure es_extended        # ou qb-core, qbx_core, selon votre framework
ensure mon_script

Sans redémarrer le serveur, chargez la nouvelle ressource depuis la console txAdmin : refresh rescanne le dossier resources et lit les manifestes, puis ensure ox_lib la démarre. Le log de démarrage doit rester silencieux. Pour vérifier que la bibliothèque répond, ouvrez le chat en jeu et tapez /ox_lib si vous avez activé ox:userLocales : le sélecteur de langue qui s'ouvre est rendu par l'interface d'ox_lib. Pour la suite de l'administration de la console, voyez notre guide configurer txAdmin.

Déclarer ox_lib dans un script

Un script n'a pas accès à lib par magie : son manifeste doit charger le fichier init.lua d'ox_lib comme script partagé, c'est-à-dire exécuté côté client et côté serveur. C'est cette ligne qui crée les globales lib, cache et require dans l'environnement du script. La ligne dependency 'ox_lib' demande en plus à FXServer de démarrer ox_lib avant le script, ce qui protège d'une erreur d'ordre dans server.cfg. Si vous commencez tout juste le Lua sur FiveM, notre tutoriel pour créer son premier script FiveM pose les bases du manifeste et des événements.

-- resources/[local]/mon_script/fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
lua54 'yes'                        -- déprécié depuis juin 2025, toléré

shared_script '@ox_lib/init.lua'   -- crée lib, cache et require
client_script 'client.lua'
server_script 'server.lua'

files { 'locales/*.json' }         -- pour lib.locale()

dependency 'ox_lib'

Le bloc facultatif ox_libs { 'locale', 'math', 'table' } précharge des modules au démarrage ; sans lui, chaque module est chargé à son premier appel, ce qui suffit dans la plupart des cas. Pour les traductions, créez locales/fr.json et locales/en.json dans votre script, appelez lib.locale() une fois, puis locale('cle') partout : la langue retenue est celle de la convar ox:locale, ou celle choisie par le joueur si ox:userLocales est actif.

Notifications, prompts et menus contextuels

Les trois fonctions que tout script finit par appeler. La notification prend une table : un title ou une description (au moins l'un des deux, la description accepte le Markdown), un type parmi inform, success, warning et error, une position (top-right par défaut, huit valeurs possibles de top à bottom-left), une duration en millisecondes (3000 par défaut), une icône Font Awesome 6 et, si vous le souhaitez, un id : deux notifications avec le même identifiant ne s'empilent pas, utile contre le spam d'un script qui se répète. Côté serveur, il n'y a pas de fonction à appeler : on déclenche l'événement client ox_lib:notify vers le joueur visé avec la même table.

-- client.lua
lib.notify({
    title = 'Garage',
    description = 'Votre **Sultan** est sortie',
    type = 'success',
    position = 'top',
    icon = 'car',
    duration = 5000
})

-- server.lua : même table, envoyée au joueur dont l'identifiant est source
TriggerClientEvent('ox_lib:notify', source, {
    id = 'solde',           -- une seule notification « solde » visible à la fois
    description = 'Solde insuffisant',
    type = 'error'
})

Le prompt, appelé TextUI dans la documentation, est le petit cadre « [E] Faire quelque chose » affiché sur un bord de l'écran. lib.showTextUI fonctionne comme un interrupteur : on l'appelle une fois pour afficher, lib.hideTextUI une fois pour masquer, et surtout pas à chaque frame. Les positions disponibles sont right-center (par défaut), left-center, top-center et bottom-center, avec icône, couleur et style CSS en option. Le module cache évite la boucle qui relit l'état du joueur en permanence : lib.onCache appelle votre fonction uniquement quand la valeur suivie change, ici le véhicule.

-- client.lua : prompt affiché quand le joueur monte dans un véhicule
lib.onCache('vehicle', function(value)
    if value then
        lib.showTextUI('[E] Démarrer le moteur', {
            position = 'left-center',
            icon = 'car'
        })
    else
        lib.hideTextUI()
    end
end)

Le menu contextuel se déclare une fois avec lib.registerContext, puis s'ouvre à la demande avec lib.showContext et son identifiant. Chaque option porte un titre, une description, une icône et une action : une fonction onSelect, un événement client event, un événement serveur serverEvent avec des arguments args, ou un sous-menu menu. Une option disabled reste visible mais grisée, et metadata affiche des détails au survol, avec une barre progress si besoin. Le champ menu au niveau du menu lui-même désigne le parent et ajoute la flèche de retour.

-- client.lua
lib.registerContext({
    id = 'garage_principal',
    title = 'Garage municipal',
    canClose = true,
    options = {
        {
            title = 'Sultan',
            description = 'Garée, place 3',
            icon = 'car',
            metadata = {
                { label = 'Carburant', value = '62 %', progress = 62 },
                { label = 'État moteur', value = 'Bon' }
            },
            serverEvent = 'mon_script:sortirVehicule',
            args = { plaque = 'ABC 123' }
        },
        {
            title = 'Dépanneuse',
            description = 'Indisponible hors service',
            icon = 'truck',
            disabled = true
        },
        {
            title = 'Options',
            icon = 'gear',
            menu = 'garage_options'   -- sous-menu enregistré par ailleurs
        }
    }
})

RegisterCommand('garage', function()
    if not lib.getOpenContextMenu() then
        lib.showContext('garage_principal')
    end
end, false)

Deux outils complètent ce trio. lib.inputDialog(titre, lignes) ouvre un formulaire et renvoie une table des valeurs saisies, ou nil si le joueur annule ; les lignes acceptent les types input, number, checkbox, select, multi-select, slider, color, date, time et textarea, avec required, default, min et max. lib.alertDialog pose une question à deux boutons et renvoie 'confirm' ou 'cancel'. Toutes ces fonctions sont asynchrones : l'appel bloque le thread Lua courant jusqu'à la réponse du joueur, ce qui rend le code linéaire et lisible.

-- client.lua : saisie puis confirmation
local saisie = lib.inputDialog('Nouvelle plaque', {
    { type = 'input', label = 'Plaque', placeholder = 'ABC 123', required = true },
    { type = 'select', label = 'Couleur', options = {
        { value = 'noir', label = 'Noir' },
        { value = 'blanc', label = 'Blanc' }
    } }
})
if not saisie then return end      -- annulé

local reponse = lib.alertDialog({
    header = 'Confirmer',
    content = 'Changer la plaque pour **' .. saisie[1] .. '** ?',
    centered = true,
    cancel = true
})
if reponse == 'confirm' then
    TriggerServerEvent('mon_script:changerPlaque', saisie[1], saisie[2])
end

ox_lib face à ESX, QBCore et Qbox

Première chose à clarifier : ox_lib n'embarque pas de « pont » vers un framework. C'est l'inverse qui se produit : les frameworks et les scripts s'appuient sur ox_lib, chacun à sa façon, et ce sont vos scripts qui décident de ce qu'ils demandent au framework (identité, métier, argent, inventaire) et de ce qu'ils confient à ox_lib (interface, callbacks, traductions). Le tableau suivant résume la situation des trois frameworks du moment, telle que la décrivent leurs manifestes.

Pour choisir entre ESX et QBCore, notre comparatif ESX Legacy ou QBCore détaille les différences ; l'installation d'ESX est couverte dans installer ESX Legacy sur FiveM. Concrètement, ce que les développeurs appellent « pont ESX/QBCore » dans un script ox_lib, c'est un petit fichier qui détecte le framework démarré et ne lui demande que les données métier. Tout le reste, notifications comprises, passe par ox_lib et devient identique sur les deux frameworks. Les callbacks d'ox_lib remplacent ESX.TriggerServerCallback et QBCore.Functions.TriggerCallback : côté serveur, lib.callback.register enregistre une fonction qui reçoit l'identifiant du joueur en premier argument ; côté client, lib.callback.await l'appelle et attend la réponse.

-- server.lua : pont minimal, le framework ne sert qu'aux données métier
local ESX, QBCore
if GetResourceState('es_extended') == 'started' then
    ESX = exports['es_extended']:getSharedObject()
elseif GetResourceState('qb-core') == 'started' then
    QBCore = exports['qb-core']:GetCoreObject()
end

local function getJob(source)
    if ESX then
        local xPlayer = ESX.GetPlayerFromId(source)
        return xPlayer and xPlayer.job.name
    elseif QBCore then
        local Player = QBCore.Functions.GetPlayer(source)
        return Player and Player.PlayerData.job.name
    end
end

lib.callback.register('mon_script:getJob', function(source)
    return getJob(source)
end)

RegisterNetEvent('mon_script:sortirVehicule', function(args)
    local source = source
    if getJob(source) ~= 'mecano' then
        TriggerClientEvent('ox_lib:notify', source, { type = 'error', description = 'Réservé aux mécaniciens' })
        return
    end
    -- ... faire apparaître le véhicule args.plaque
end)

-- client.lua : la réponse arrive dans la même ligne, sans callback imbriqué
local job = lib.callback.await('mon_script:getJob', false)
if job == 'mecano' then
    lib.showContext('garage_principal')
end

Un script du marché conçu pour ox_lib vous demandera rarement plus que cela : ses fichiers de configuration proposent en général le choix du framework et, parfois, du système de notification. Avant d'en acheter un, notre guide scripts FiveM, où les trouver et lesquels éviter liste ce qu'il faut vérifier, et nos tutoriels pour installer Quasar Inventory et installer LB Phone montrent deux ressources courantes qui déclarent ox_lib en dépendance.

Déboguer les erreurs de dépendances les plus fréquentes

La console txAdmin et la console F8 du client donnent presque toujours le diagnostic. Les messages ci-dessous sont ceux que produisent ox_lib, cfxlua-require et FXServer, par ordre de fréquence dans les tickets.

Pour isoler une panne, les commandes de ressource de la console txAdmin suffisent, sans toucher aux fichiers : stop ox_lib arrête la ressource, start ox_lib la démarre si elle était arrêtée, restart ox_lib la relance, et ensure ox_lib fait l'un ou l'autre selon son état. Pour désactiver ox_lib le temps d'un test, mettez sa ligne ensure en commentaire avec un # dans server.cfg et redémarrez : tous les scripts qui le déclarent en dépendance cesseront de fonctionner, ce qui vous dit au passage lesquels en dépendent réellement. Si un comportement subsiste avec ox_lib seul sur un serveur de test, sans aucun autre script, c'est un bug à signaler sur le dépôt GitHub, avec la version d'ox_lib, celle de cfxlua-require, le numéro des artefacts et le log complet ; sinon, c'est une erreur de config ou un conflit entre scripts, et le dépôt vous renverra vers votre installation.

Trois réflexes évitent la plupart de ces tickets. Mettez à jour ox_lib et cfxlua-require ensemble, toujours depuis la même archive, en supprimant les anciens dossiers plutôt qu'en les écrasant. Lisez le log complet au démarrage, pas seulement la dernière ligne : la première erreur en haut de la pile est la cause, les suivantes sont des conséquences. Enfin, lib.versionCheck('overextended/ox_lib') dans un script serveur interroge l'API GitHub et signale en console quand une nouvelle version d'ox_lib est publiée, ce qui vous évite de découvrir un retard de dix versions le jour où un script refuse de démarrer. Pour tout ce qui touche au démarrage du serveur lui-même, notre page solutions aux erreurs courantes sur FiveM complète ce tableau.

Lexique : ressource, plugin, package, runtime, environnement

Les tickets sur ox_lib mélangent souvent le vocabulaire de FiveM avec celui d'autres serveurs de jeu ou de l'hébergement web. Ces définitions fixent les termes utilisés dans ce guide et dans la documentation d'Overextended.

Conclusion

Installer ox_lib sur un serveur FiveM tient en trois gestes, sous Windows comme sur un VPS Linux ou depuis un panel : extraire l'archive de release complète, ox_lib et cfxlua-require côte à côte dans resources, écrire ensure ox_lib avant les scripts qui l'utilisent dans server.cfg, et fixer ox:locale fr pour une interface en français. Chaque script y accède ensuite par une ligne de manifeste, shared_script '@ox_lib/init.lua', et gagne des notifications, des prompts, des menus contextuels, des dialogues et des callbacks identiques quel que soit le framework, ESX Legacy, QBCore ou Qbox. Les pannes se lisent dans la console, et presque toutes se ramènent à un ordre de démarrage, un dossier manquant ou une mise à jour incomplète. Le manifeste d'ox_lib cible aussi RedM, la bibliothèque sert donc également sur un serveur RedM. Pour que l'interface reste fluide avec cinquante scripts qui l'appellent, le serveur doit suivre : nos offres serveur FiveM vont de 4 à 64 Go de RAM DDR4, avec txAdmin et protection anti-DDoS inclus, hébergées en France, et si vous préférez gérer FXServer vous-même, notre guide FiveM sous Docker sur un VPS Linux couvre l'installation complète.