How to Extract .gma Files: The Complete Garry’s Mod Addon Guide

What a .gma file is

.gma stands for Garry's Mod Addon. It bundles everything an addon needs — Lua scripts, models, materials, sounds, maps — into one file, along with a small header holding the addon's name, type, tags and author. Every addon on the Garry's Mod Workshop is shipped this way.

Two details explain most of the confusion around these files. First, the format is custom, so standard archivers have no idea how to read it. Second, when you obtain a .gma directly from Steam's content servers it is LZMA-compressed on top of the container format, which is why the first bytes look like binary noise rather than a file table.

The tool that understands both layers is gmad, Valve and Facepunch's own packer. It ships inside Garry's Mod.

Do you actually need to extract it?

Often not, and it is worth checking before you start. Garry's Mod reads .gma files natively: drop one into garrysmod/addons/, restart, and the addon is active. There is no unpacking step in a normal install. If your goal is simply "use this addon", see downloading Garry's Mod addons without Steam instead — the install is a file copy.

Extraction earns its keep when you want to:

• Import models or materials into Source Filmmaker, Blender, or another Source tool
• Read an addon's Lua to understand how something was built
• Pull a single map out of a pack rather than mounting the whole thing
• Fix or patch an addon whose author has stopped updating it
• Audit what an addon actually contains before running it on a server

Extracting with gmad.exe on Windows

gmad lives in your Garry's Mod installation:

C:\Program Files (x86)\Steam\steamapps\common\GarrysMod\bin\gmad.exe

If your Steam library is on another drive, adjust accordingly — the tail of the path (steamapps/common/GarrysMod/bin) is what stays constant.

The command

Open Command Prompt or PowerShell, change into that bin folder, and run:

gmad.exe extract -file "C:\gmod-addons\my_addon.gma"

That unpacks the addon into a folder next to the .gma. To choose the destination yourself, add -out:

gmad.exe extract -file "C:\gmod-addons\my_addon.gma" -out "C:\gmod-addons\extracted\my_addon"

Put together, a full session looks like this:

cd "C:\Program Files (x86)\Steam\steamapps\common\GarrysMod\bin"
gmad.exe extract -file "C:\Users\You\Downloads\my_addon.gma"

The drag-and-drop shortcut

For occasional use there is a quicker way that needs no typing: drag the .gma file directly onto gmad.exe in Explorer. gmad treats a dropped file as an extract request and unpacks it beside the original. A console window flashes briefly and a new folder appears.

Extracting on Linux and macOS

The Linux build is named gmad_linux and sits in the same bin folder. The arguments are identical:

cd ~/.steam/steam/steamapps/common/GarrysMod/bin
./gmad_linux extract -file ~/Downloads/my_addon.gma -out ~/extracted/my_addon

If it refuses to run, mark it executable first with chmod +x gmad_linux.

On macOS, Garry's Mod ships inside an app bundle, so the binary is nested further down — look under GarrysMod/garrysmod.app/Contents/MacOS/bin/. Since the 64-bit transition, the simplest path for Mac users is often to extract on a Windows or Linux machine, or to run the Windows gmad.exe under Wine.

Extracting many files at once

If you have archived a whole collection, extracting one at a time gets old fast. On Windows, save this as extract-all.bat in the folder holding your .gma files:

@echo off
set GMAD="C:\Program Files (x86)\Steam\steamapps\common\GarrysMod\bin\gmad.exe"
set OUT=C:\gmod-addons\extracted

for %%F in ("C:\gmod-addons\*.gma") do (
  echo Extracting %%~nxF
  %GMAD% extract -file "%%~fF" -out "%OUT%\%%~nF"
)
echo Done.
pause

The Bash equivalent:

#!/usr/bin/env bash
set -euo pipefail

GMAD="$HOME/.steam/steam/steamapps/common/GarrysMod/bin/gmad_linux"
OUT="$HOME/extracted"

mkdir -p "$OUT"
for f in ~/gmod-addons/*.gma; do
  name="$(basename "$f" .gma)"
  echo "Extracting $name"
  "$GMAD" extract -file "$f" -out "$OUT/$name"
done

Both loop over every .gma in a directory and unpack each into its own subfolder named after the file, which keeps addons from overwriting one another's materials and models trees.

What's inside an extracted addon

Once unpacked you get an ordinary directory tree, mirroring the layout Garry's Mod expects:

my_addon/
├── addon.json
├── lua/
│   ├── autorun/
│   └── weapons/
├── materials/
│   └── models/
├── models/
│   └── weapons/
└── sound/
    └── weapons/

What each folder holds:

• lua/ — the addon's code. autorun/ runs at startup; weapons/ and entities/ define things you can spawn.
• models/ — geometry, as .mdl plus its companion .vvd, .vtx and .phy files.
• materials/ — textures as .vtf and their .vmt material definitions.
• sound/ — audio, usually .wav or .mp3.
• maps/ — compiled maps as .bsp, if the addon includes any.
• addon.json — the metadata gmad reads when packing.

A typical addon.json:

{
  "title": "My Addon",
  "type": "weapon",
  "tags": ["fun", "roleplay"],
  "ignore": ["*.psd", "*.vcproj", "*.svn*"]
}

The ignore array lists patterns excluded at pack time, which is how source files like .psd artwork stay out of the shipped addon.

Repacking a folder back into a .gma

gmad works in both directions. Once you have edited an extracted addon, pack it again with:

gmad.exe create -folder "C:\gmod-addons\extracted\my_addon" -out "C:\gmod-addons\my_addon_repacked.gma"

The folder must contain a valid addon.json or the command will fail — that file is where gmad gets the title and type. If you extracted the addon in the first place it will already be there.

When extraction fails

"Invalid file" or "not a valid gma"

Nearly always an incomplete download. Check the file size on disk against the size shown on the Workshop page — a 3 KB file for a 40 MB addon never finished. Download it again and compare before extracting.

The other possibility is that the file is not a .gma at all. Some browsers save without an extension, and a few save an HTML error page under the expected filename. Opening it in a text editor tells you immediately: an HTML error page is readable, a real .gma is not.

gmad.exe is not in the bin folder

Verify your Garry's Mod install through Steam (right-click the game, Properties, Installed Files, Verify integrity). gmad is part of the game files and a failed update can leave it missing.

The command runs but nothing appears

Check where you actually ran it from. Without -out, gmad writes next to the .gma, not into your current directory. Passing an explicit -out removes the ambiguity.

Extracted models show up pink and black in-game

That checkerboard is Source's missing-texture placeholder. It means the materials folder did not end up where the .mdl expects it — usually because assets from several addons were extracted into one folder and overwrote each other. Extract each addon separately.

Frequently Asked Questions

Summary

.gma is Garry's Mod's own addon container, and gmad — sitting in your game's bin folder — is the tool that reads it. One command with -file and -out unpacks any valid addon into ordinary folders, and gmad create puts it back together.

Before you extract anything, though, check whether you need to. If you just want to play with the addon, dropping the .gma straight into garrysmod/addons/ is the entire installation.