free: Usage, Options & Common CI Errors
free reports how much RAM and swap are used, free, and available.
free is the memory companion to df. It is what you check when a build is OOM-killed (exit 137): the "available" column, not "free", is the number that actually matters.
What it does
free displays total, used, free, shared, buffer/cache, and available memory plus swap. "available" estimates how much a new process can use without swapping - the meaningful figure, since the kernel uses spare RAM as cache.
Common usage
free -h # human-readable
free -m # in MiB
free -h -s 2 # refresh every 2 seconds
free -h | awk '/Mem:/ {print $7}' # available column
cat /proc/meminfo # detailed source dataOptions
| Flag | What it does |
|---|---|
| -h | Human-readable units |
| -m / -g | Show in MiB / GiB |
| -s <secs> | Repeat every N seconds |
| -t | Add a total (RAM + swap) line |
| -w | Wide output (split buffers/cache) |
Common errors in CI
A step killed with exit code 137 (128+9, SIGKILL) is usually the OOM killer - free -h beforehand shows the headroom. Watch the available column, not free: low "free" with high buff/cache is normal and healthy. "free: command not found" on minimal/Alpine images - read /proc/meminfo instead. In containers, free may show the HOST memory, not the cgroup limit, so it can mislead about the real ceiling.