nproc Command: Tutorial & Examples

One number, instantly — the count of processing units available to your programs right now.

What It Is

nproc prints the number of CPU cores available to you, and nothing else. Type five letters, get one number, done. It sounds too trivial to need a page — but that one number is the denominator for almost every performance judgement you'll ever make on a Linux box, and there's a genuinely surprising twist hiding in the word available that trips up even experienced admins. So let's get it exactly right.

You reach for it constantly without thinking: is a load average of 6 bad? Depends — nproc tells you against what. How many parallel jobs should a build run? nproc is the answer you feed to make -j. It ships in coreutils, so it's on every Linux machine already, it changes nothing, and it's safe to run anywhere. This page is short, but by the end you'll understand the one thing about it that actually matters.

Your First Look

nproc

8

That's it — eight logical CPUs on this machine. Now the first subtlety, and it's a good one:

nproc --all

8

Plain nproc reports the cores available to the current process; nproc --all reports the cores the machine physically has. On a normal server they're equal — but the gap between those two numbers is where all the interesting truths live, and we'll get there in a moment.

How I Read It

Honestly, nproc isn't a number I read so much as a number I divide by. The instant I see a load average or a busy top screen, my next reflex is "out of how many cores?" — and nproc answers in under a second. A load of 7.5 is a sleepy afternoon on this 8-core box and a five-alarm fire on a 1-core VM. Same number, opposite meaning, and nproc is what disambiguates them.

The one habit worth burning in: when nproc and nproc --all disagree, stop and ask why. That disagreement is never random — something has deliberately fenced your process into fewer cores than the hardware has, and that something is usually cgroups, a container limit, or CPU affinity. Nine times out of ten it explains a performance mystery you were about to chase in the wrong place.

The Number, Explained

nproc counts logical CPUs, not physical ones — and on modern hardware those are very different things. A logical CPU is anything the kernel's scheduler can hand a thread to. That includes hyperthreads (Intel) or SMT siblings (AMD): the trick of presenting one physical core as two logical ones, so the core can keep working on one thread while the other waits on memory. A 4-core hyperthreaded chip reports 8. That extra hyperthread is real but it is not a whole core — figure roughly 1.3× throughput from the pair, not 2× — so when you size work against nproc, remember the back half of those "cores" are worth less than the front half.

Where does the number come from? nproc is just reading what the kernel already publishes. Every logical CPU shows up as a processor: line in /proc/cpuinfo, so this gives the same answer:

grep -c ^processor /proc/cpuinfo

8

nproc is the polite, portable front-end to that count, with one crucial extra: it also honors the limits placed on your process, which raw /proc/cpuinfo does not.

The Magic: nproc Counts Your Cage, Not the Building

Here's the part worth the whole page. nproc (without --all) respects CPU affinity — the set of cores your process is actually allowed to run on. Pin a command to two cores and ask it how many CPUs it has:

taskset -c 0,1 nproc

2

The machine still has 8. But this process was fenced to cores 0 and 1, so nproc honestly reports 2 — because from that process's point of view, 2 is the truth. The same thing happens, invisibly, inside a Docker container with --cpus=2, or in a cgroup with a CPU quota, or under a batch scheduler. Your program runs nproc, gets a small number, sizes its thread pool to match — exactly as it should.

This is why a well-behaved program uses nproc and not /proc/cpuinfo: it automatically right-sizes itself to the slice it was actually given, instead of greedily spawning 64 threads on a box where it's only allowed 4 cores and then thrashing the scheduler. Once you've seen taskset -c 0,1 nproc print 2, the whole "available vs installed" distinction clicks, and you'll never again confuse "how big is the server" with "how much of it is mine."

nproc also obeys the OMP_NUM_THREADS environment variable (the OpenMP knob), capping its answer to whatever you set — handy for telling a parallel library to behave:

OMP_NUM_THREADS=2 nproc

2

Reading It by Example

A few readings and what each one tells me, all on the same physical machine:

nproc → 8, nproc --all → 8. Bare metal or a full VM, nothing fenced. Use 8 as your divisor and your -j. The normal, boring, happy case.

nproc → 2, nproc --all → 8. You're in a cage. A container CPU limit, a cgroup quota, or affinity is holding this process to a quarter of the box. If something feels slow, this is probably why — and the fix is the limit, not the code.

nproc → 96. A big machine — or a misread. Double-check it's not counting hyperthreads you're treating as full cores; 96 logical often means 48 physical. Size memory and licensing against physical, parallelism against logical.

nproc → 1. A tiny VM. Now any sustained load average above ~1 means work is queueing, and a single runaway process can wedge the whole box. The cheapest cloud tiers live here.

Cheat Sheet

nproc — cores available to this process (respects affinity, cgroups, OMP_NUM_THREADS)
nproc --all — cores the machine physically has, ignoring all limits
nproc --ignore=N — subtract N from the count (e.g. make -j"$(nproc --ignore=1)" to leave one core free)
grep -c ^processor /proc/cpuinfo — the raw physical count, the long way
taskset -c 0,1 cmd — run cmd pinned to cores 0–1 (and watch its nproc shrink)

The idiom you'll write most, parallel builds sized to the box:

make -j"$(nproc)"

How You'll Actually Use It

You'll almost never run nproc on its own and stare at it. It lives inside other commands as a divisor or a degree of parallelism. Sizing a build: make -j"$(nproc)". Keeping one core free for everything else while you compile: make -j"$(nproc --ignore=1)". Feeding a parallel tool: xargs -P "$(nproc)", or rsync helpers, or a thread-pool flag. And whenever you read top, uptime, or mpstat, nproc is the silent denominator in your head.

Gotchas

nproc counts logical CPUs, including hyperthreads. 8 may be 4 real cores. Size parallel CPU work against nproc; size things that care about real cores (some licenses, NUMA tuning) against the physical count.
Plain nproc can lie low on purpose. Inside a container or under cgroup/affinity limits it reports your slice, not the host. That's a feature — but if nproc and nproc --all disagree, know which question you're really asking.
/proc/cpuinfo ignores your cage. grep -c ^processor /proc/cpuinfo always shows the host's logical count, even when your process can only use two of them. Use nproc when you mean "cores I'm allowed to use."
It's a snapshot. CPUs can be hot-plugged or offlined (/sys/devices/system/cpu/cpu*/online); nproc reflects the count at the moment you ran it.

History & Philosophy

nproc is a GNU coreutils tool, and it embodies the best Unix instinct: do one thing, print one number, compose into everything else. There's no interactive mode, no flags worth a paragraph, no output to parse — just a value you drop into $(...) and forget. That's why it has outlived a dozen fancier "system info" tools: it's small enough to be a verb in your shell sentences.

And the deeper lesson it quietly teaches is the one most beginners miss — that "how big is this machine" and "how much of it do I get" are different questions. Virtualization, containers, and cgroups slice one physical box into many logical allowances, and nproc is the little command that tells you the size of your allowance. Internalize that, and you've understood something fundamental about how modern shared infrastructure actually works.