How to Install Custom Weapons in FiveM [2026]

What Are Custom Weapons in FiveM?

• Tactical rifles & military-grade firearms
• Realistic pistols & revolvers with custom animations
• Suppressed and modded weapon variants
• Melee weapons — batons, knives, machetes
• Law enforcement tools — tasers, pepper spray, stingers
• Prop weapons & roleplay-only items (radios, handcuffs, medkits)

If your scripts define your server's economy and your MLOs define your world, custom weapons define your server's combat identity. They're essential for military RP, gang RP, police RP, and any server where firefights are part of the experience.

Why Add Custom Weapons to Your Server

Did you know? FiveVault hosts weapon packs and resources tagged by framework compatibility — ESX, QBCore, QBOX, OX Core, and Standalone. Browse all weapon resources →

Prerequisites

Step 1: Understand How Custom Weapons Work in FiveM

Custom weapons in FiveM come in two types — it's important to know which one you're installing:

Replaces the model and texture of an existing GTA V weapon while keeping its stats and animations.

my-weapon-pack/
├── stream/
│   ├── w_pi_pistol.ydr        ← replaces default pistol model
│   └── w_pi_pistol.ytd        ← replaces default pistol texture
└── fxmanifest.lua

Adds an entirely new weapon with its own weapon hash, name, and stats. Requires framework registration to give to players.

my-addon-weapon/
├── stream/
│   ├── w_custom_taser.ydr
│   └── w_custom_taser.ytd
├── data/
│   └── weaponarchetypes.meta
│   └── weapons.meta
│   └── weaponanimations.meta
└── fxmanifest.lua

Pro tip: Replacement weapons are easier to install — they work automatically once streamed. Addon weapons require additional metadata registration and framework config. FiveVault's weapon tags will tell you which type you're downloading.

Step 2: Download Your Weapon Pack

Head to FiveVault and pick a weapon pack. Once downloaded, extract the .zip or .rar. Check for the folder structure shown in Step 1 to confirm whether it's a replacement or addon weapon.

Pro tip: Always check the framework tag before downloading. A weapon pack tagged "Standalone" works on any server. One tagged "ESX" or "QBCore" requires framework-specific registration in your inventory system.

Step 3: Import the Weapon Metadata (Addon Weapons Only)

If your weapon pack is an addon weapon (has a data/ folder with .meta files), you need to declare these in fxmanifest.lua. Open the manifest and confirm these data files are registered:

fx_version 'cerulean'
game 'gta5'

description 'My Custom Weapon Pack'
version '1.0.0'

data_file 'WEAPONARCHETYPES_FILE'  'data/weaponarchetypes.meta'
data_file 'WEAPON_METADATA_FILE'   'data/weapons.meta'
data_file 'WEAPON_ANIMATIONS_FILE' 'data/weaponanimations.meta'

files {
    'data/*.meta'
}

If any of these data_file lines are missing but the corresponding .meta file exists in the folder — add them manually. Missing metadata is the most common cause of addon weapons not working.

Step 4: Upload to Your Server's Resources Folder

Connect via SFTP or your hosting panel's file manager. Upload the weapon pack into a dedicated subfolder:

resources/
└── [weapons]/
    └── my-weapon-pack/

Do not rename the folder after uploading — the name must match exactly what you put in server.cfg.

Step 5: Add the Weapon to server.cfg

Open your server.cfg and add the ensure line. Place it before your inventory system:

# Inventory (must load after weapon streams)
ensure ox_inventory
# or
ensure qb-inventory

# Weapons (load before inventory)
ensure [weapons]/my-weapon-pack
ensure [weapons]/police-taser-pack
ensure [weapons]/gang-weapon-pack

Step 6: Register the Weapon as an Item in Your Inventory

['custom_taser'] = {
    label = 'Custom Taser',
    weight = 500,
    stack = false,
    close = true,
    description = 'A custom police taser.',
},

['custom_taser'] = {
    name = 'custom_taser',
    label = 'Custom Taser',
    weight = 500,
    type = 'item',
    image = 'custom_taser.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'A custom police taser.'
},

INSERT INTO items (name, label, weight)
VALUES ('custom_taser', 'Custom Taser', 500);

Pro tip: The item name must exactly match the weapon hash defined in weapons.meta. Open the .meta file and look for — that's your hash/item name.

Step 7: Give the Weapon to Players

Once registered, you can give the weapon to players using standard framework commands or scripts.

-- Give a weapon to a player by server ID
TriggerClientEvent('weapons:giveWeapon', playerId, 'WEAPON_CUSTOM_TASER', 100)

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.addInventoryItem('custom_taser', 1)

local Player = QBCore.Functions.GetPlayer(source)
Player.Functions.AddItem('custom_taser', 1)

/giveweapon [playerid] custom_taser 100

Step 8: Restart and Test

Restart the weapon resource in your txAdmin console or server console:

restart [weapons]/my-weapon-pack

Join your server and give the weapon to a test character. For replacement weapons, the existing spawn name works:

/giveweapon [playerid] WEAPON_PISTOL 100

For addon weapons, use the custom hash from weapons.meta:

/giveweapon [playerid] WEAPON_CUSTOM_TASER 100

If the weapon spawns with the correct model — you're done.

Framework Compatibility

Troubleshooting Common Weapon Issues

❌ Weapon spawns but shows original GTA model

❌ Addon weapon causes server crash on startup

❌ "Could not find resource" error in console

❌ Weapon item exists in inventory but has no model (invisible weapon)

❌ Weapon animations are broken or T-pose on equip

❌ ox_inventory doesn't recognise the weapon item

❌ QBCore shop doesn't show the weapon

Recommended Weapon Resources for Your Server

Final Tips

• ✅ Know your weapon type — replacement vs. addon have completely different install steps
• ✅ Match stream filenames exactly — one character wrong and the replacement won't apply
• ✅ Declare all .meta files in fxmanifest.lua — missing data files cause crashes
• ✅ Load weapon streams before your inventory in server.cfg
• ✅ Match item names to weapon hashes — they must be identical for addon weapons
• ✅ Test on a dev server first — a broken weapons.meta will crash your entire server on startup
• ✅ Source from FiveVault — quality-checked packs reduce broken metadata issues
• ✅ Back up server.cfg before every session of adding new weapon resources

Frequently Asked Questions

A: No — FiveM streams weapon assets to players automatically when they join the server.

A: Not directly. SP weapon mods use a different format. They need to be converted to FiveM addon format first — look for FiveM-converted versions on trusted platforms like FiveVault.

A: Yes — most inventory systems (ox_inventory, qb-inventory) support job-gated items. Only players with the correct job can carry or purchase the weapon.

A: A replacement swaps the look of an existing GTA weapon — it uses the same hash and stats. An addon adds a brand new weapon with its own hash, stats, and animations — it needs full registration.

A: SP and FiveM use different streaming systems. The weapon files need to be in FiveM's resource format with a valid fxmanifest.lua and correct data_file declarations.

A: Yes — if two replacement packs both replace the same weapon (e.g., both replace w_pi_pistol), whichever loads last in server.cfg wins. Addon weapons rarely conflict unless they share the same weapon hash.