FiveM Peds: How to Add Custom Peds and Ped Models (2026)

A ped is any character model in GTA V: your own player, an NPC, a police officer, a dog. Adding peds to a FiveM server comes down to three things. The model files go in the stream folder of a resource, that resource gets an fxmanifest.lua, and you start it from server.cfg. After that you can switch to the ped by its model name or spawn it as an NPC.

This guide covers each step, with links to the parts of the official FiveM documentation that matter for peds.

How to add a ped to FiveM: the short version

1. Download a ped that is released as an add-on ped for FiveM. You need the model files (.yft, .ymt, .ydd and .ytd) and, for most add-on peds, a peds.meta.
2. Create a resource folder inside resources, for example resources/[peds]/my-peds.
3. Put the model files in a folder called stream inside it.
4. Add an fxmanifest.lua, with a data_file line for the peds.meta if the ped has one.
5. Add ensure my-peds to server.cfg and restart the server.
6. In game, switch to the ped by its model name: the file name of the .yft without the extension.

On our FiveM server hosting, ped resources, EUP packs and streamed clothing are uploaded like any other resource, through the control panel or SFTP.

What peds are in FiveM

In FiveM you can:

• add new character models next to the existing ones (add-on peds, often written "addon peds")
• replace an existing GTA V model with a custom one (replace peds)
• stream extra clothing for the multiplayer characters mp_m_freemode_01 and mp_f_freemode_01
• use EUP (Emergency Uniforms Pack) for police, fire and EMS uniforms

Most roleplay servers use clothing for their players and a handful of add-on peds for special roles, pets or NPCs.

Add-on peds, replace peds and clothing

Add-on peds are the safer choice. A replace ped changes every place the game uses that model, including ambient pedestrians and scripts that spawn it. Clothing is what most RP servers use for uniforms and outfits, because players keep their own face, hair and body.

Where to find ped models

• The player section of GTA5-Mods. Look for "Add-On Ped" in the title, and check the description for FiveM instructions. Many uploads there are single-player replace mods.
• Release threads on the Cfx.re forum, where creators post FiveM-ready resources.
• Paid ped packs on Tebex stores. These are often escrowed: Cfx.re's asset escrow supports YFT and YDD files, the formats ped models are built from (Asset Escrow docs). An escrowed ped only starts on a server whose license key belongs to the Cfx.re account that owns it. Our Cfx Portal guide explains keys, granted assets and transfers.

Installing an add-on ped step by step

1. Build the resource folder

FiveM treats every folder inside resources as a resource. Folders in square brackets, such as [peds], are categories that can hold several resources (Introduction to Resources).

resources/
  [peds]/
    my-peds/
      fxmanifest.lua
      peds.meta
      stream/
        my_ped.yft
        my_ped.ymt
        (the .ydd and .ytd files of the ped)

Game asset files go in stream, the same way the FiveM docs set up their own map resource example. FiveM streams them to players without any extra line in the manifest. Keep the file names exactly as the author shipped them: the model name comes from the .yft, and the .ymt and component files belong to it by name.

2. Write the fxmanifest.lua

Every resource needs an fxmanifest.lua (Resource Manifest docs). For a ped with a peds.meta:

fx_version 'cerulean'
game 'gta5'

files {
    'peds.meta'
}

data_file 'PED_METADATA_FILE' 'peds.meta'

cerulean is the current manifest version and game 'gta5' marks the resource for FiveM. PED_METADATA_FILE is the data file type for peds.meta in the official data file list, and the file also has to be listed under files, as in the manifest docs' own data_file example. If your ped came without a peds.meta, keep only the first two lines.

More manifest options are in our fxmanifest.lua reference.

3. Start the resource

Add it to server.cfg:

ensure my-peds

ensure starts a resource, or restarts it when it is already running. On a server that is already up, run refresh in the console first so FiveM rescans the resources folder, then ensure my-peds. You can also start a whole category with ensure [peds] (server commands). If you add peds while people are online, reconnect before you test.

4. Switch to the ped in game

Most admin menus and frameworks have a "change ped" option where you type the model name. To test without a menu, this client script adds a /setped command. It follows the example on the official SET_PLAYER_MODEL page: check that the model exists, request it, wait until it has loaded, then apply it.

-- client.lua
RegisterCommand('setped', function(source, args)
    local model = GetHashKey(args[1] or 'a_m_y_hipster_01')

    if not IsModelInCdimage(model) or not IsModelValid(model) then
        print('Unknown ped model: ' .. tostring(args[1]))
        return
    end

    RequestModel(model)
    while not HasModelLoaded(model) do
        Wait(0)
    end

    SetPlayerModel(PlayerId(), model)
    SetPedDefaultComponentVariation(PlayerPedId())
    SetModelAsNoLongerNeeded(model)
end, false)

Add client_script 'client.lua' to the manifest. Two details from the docs are worth knowing. SET_PLAYER_MODEL destroys the player's current ped and creates a new one, so a script that stored the old ped handle has to get it again with PlayerPedId(). SET_PED_DEFAULT_COMPONENT_VARIATION gives the new ped its default clothes.

Anyone who types this command can change their own ped. Keep it on a test server, or put ped changes behind your framework's admin permissions on a live one.

If players spawn through the standard spawnmanager resource, its spawnPlayer export also takes a model field. Without it, the player keeps the ped they had before (spawnPlayer docs).

Spawning a ped as an NPC

For shopkeepers, guards or a police dog you spawn the ped instead of becoming it. CREATE_PED also needs the model to be loaded first (CREATE_PED):

local model = GetHashKey('s_m_y_cop_01')
RequestModel(model)
while not HasModelLoaded(model) do
    Wait(0)
end

-- use your own coordinates and heading
local ped = CreatePed(4, model, 441.0, -978.0, 30.7, 180.0, false, false)
SetModelAsNoLongerNeeded(model)

The docs say the first argument is unused, because the game picks the ped type itself. The first false after the heading makes the ped exist only on the client that runs the script. Set it to true for a networked ped. NPC resources and most frameworks wrap all of this for you.

FiveM ped model names

For base game models, the FiveM docs keep a ped model list with a picture and the model name of each ped. It is grouped into ambient, animal, cutscene, gang, multiplayer, scenario and story peds. A few you will use often:

The page says it lists the working models as of July 23, 2019, so peds from later GTA Online updates can be missing. Those models only exist on your server when it runs a game build that includes them. You set the build with sv_enforceGameBuild in server.cfg, only at startup, and every build includes the content of the builds before it (sv_enforceGameBuild).

FiveM for GTA V Enhanced: the stream_enhanced folder

FiveM for GTA V Enhanced is in early access (see our Enhanced guide for server owners). According to the official FiveM docs repository, resources can now include a stream_enhanced folder next to stream. On Enhanced, FiveM loads stream_enhanced instead of stream when it is there, and falls back to stream when it is not. Cfx.re calls the plain stream folder deprecated on Enhanced and suggests Legacy assets in stream and Enhanced assets in stream_enhanced, so one resource works on both (What's changed in FiveM for GTAV Enhanced, source on GitHub).

To convert Legacy models, Cfx.re publishes Alchemist. It handles YDR, YTD, YFT, YPT and YDD files and runs on Windows 11 (Alchemist docs).

EUP and custom clothing

EUP adds police, fire and EMS uniforms as clothing for the two multiplayer models, so players keep their own character while wearing them. Clothing packs usually ship with their own manifest and meta files. Install them as they come and use the start order from the pack's readme. Each piece sits in a numbered component slot (tops, legs, shoes and so on), so a shirt that shows up on the wrong body part points to a naming or slot mistake in the pack.

Full walkthroughs: the FiveM EUP installation guide and custom clothing and EUP.

Size and performance

Players download the files in stream from your server and keep them in their FiveM cache, so a big ped or clothing pack costs download time for players who do not have it yet, and disk space on the server. Check the size of a pack before you add it, and remove peds nobody uses. If your ped and vehicle library keeps growing, our FiveM server hosting plans start at 2GB and scale to 32GB.

Common errors and fixes

You stay the same model

• Check that the resource started. Read the server console after ensure. A warning that the resource "does not have a resource manifest (fxmanifest.lua)" means the file is missing or misnamed, often because the zip was unpacked with an extra folder level.
• Check the model name. It is the .yft file name without the extension. If IsModelInCdimage returns false for that name, the model is not being streamed.
• Check that the script waits for the model. The docs for SET_PLAYER_MODEL and CREATE_PED both say to request the model and wait until it has loaded.

The ped is invisible or parts are missing

Compare the stream folder with the original download. A missing or renamed .ydd or .ytd file is the most common cause. Also call SetPedDefaultComponentVariation after a model switch, as in the example above.

peds.meta changes do nothing

The peds.meta has to be in the files block and loaded with data_file 'PED_METADATA_FILE' 'peds.meta'. Both lines are needed, with the exact file name.

A GTA Online ped does not exist on your server

The model comes from an update newer than your game build. Raise sv_enforceGameBuild and restart the whole server, because the build is only read at startup.

"You lack the required entitlement"

The ped is escrowed and your server's license key belongs to a different Cfx.re account than the one that owns the asset. Use a key from the owning account or transfer the asset, as explained in the Cfx Portal guide.

Textures load late or look blurry

With many streamed models and interiors around a player, textures can load late or stay at low detail. Our texture loss and headpopping fix covers what to check.

EUP does not show up in the menu

The menu script is not configured, or the packs start in the wrong order. Follow the start order from the readme of each pack.

FAQ

How do I add peds to my FiveM server? Put the ped's model files in the stream folder of a resource, add an fxmanifest.lua (with data_file 'PED_METADATA_FILE' 'peds.meta' if the ped has a peds.meta), add ensure plus the resource name to server.cfg and restart the server.

What is the spawn name of a custom ped? The file name of its .yft without the extension. For base game peds, look up the name in the ped model list on docs.fivem.net.

What is EUP in FiveM? Emergency Uniforms Pack, a widely used clothing pack that adds police, fire and EMS uniforms to the multiplayer character models.

Do custom peds cause lag? They add to what players download from your server and to what their game has to load. The cost grows with the size and number of peds you stream, so keep packs lean and remove models nobody uses.

Can players add their own custom peds? No. Peds are installed on the server, and players use the models the server streams to them.

Related: How to install FiveM mods, FiveM addon cars guide, FxManifest.lua reference, FiveM Lua scripting for beginners