← Full reference

flock

File locks from the shell — keep two copies of a script or cron job from running at the same time

flock takes a lock on a file (the flock(2) system call) and runs a command while holding the lock. If another process already holds the lock, flock waits or gives up right away. The main use is protection against concurrent runs: a cron job that hasn't finished by the next run, a deploy script, a queue worker. The lock is released automatically when the owning process exits, even if it crashes — unlike "pid files", which stay behind after a crash. The tool is part of util-linux.

Syntax

flock [options] file command [args…]    # lock the file for the duration of the command
flock [options] file -c 'command string'      # command via sh -c
flock [options] fd_number                      # lock an already open descriptor

The lock file is created if it doesn't exist (the directory must exist). The file contents don't matter — the lock is tied to the file itself, not to the data.

Options

OptionWhat it does
-x, --exclusiveexclusive lock — only one owner (default)
-s, --sharedshared lock — several "readers" at once, but not together with -x
-n, --nonblockdon't wait: if busy, exit immediately with code 1
-w sec, --timeoutwait no longer than N seconds (fractions allowed), then exit with code 1
-E codeexit code for a busy lock or timeout instead of 1
-u, --unlockrelease the lock on a descriptor (usually unnecessary — released on close)
-o, --closeclose the lock descriptor before running the command: its children won't inherit the lock
-c 'commands'run the string via sh -c
-F, --no-forkdon't fork a child process, replace flock with the command
--verbosereport how long it waited for the lock and what it runs

Exit codes

CodeWhen
the command's codelock acquired, the command ran
1lock is busy (-n) or the timeout expired (-w); or your own value from -E
66the lock file couldn't be opened (e.g. the directory doesn't exist)

Two ways to use it

FormExampleWhen
wrapper around a commandflock -n /run/job.lock /opt/job.shin a crontab, when you don't want to change the script
descriptor inside a scriptexec 9>/run/job.lock; flock -n 9 || exit 1the script protects itself; the lock lives until the script ends

Examples

# cron: run every minute, but don't let runs overlap
# * * * * * flock -n /run/backup.lock /opt/backup.sh

# wait for the lock no longer than 30 seconds
flock -w 30 /run/deploy.lock ./deploy.sh || echo "deploy already in progress" >&2

# tell "busy" apart from a failure of the command itself
flock -n -E 75 /run/job.lock ./job.sh
[ $? -eq 75 ] && echo "already running"

# a script that protects itself: the lock is held for the whole run
cat > /tmp/job.sh <<'EOF'
#!/bin/bash
exec 9>/tmp/job.lock
if ! flock -n 9; then
    echo "another copy is already running" >&2
    exit 1
fi
echo "working, PID $$"
sleep 5
EOF
chmod +x /tmp/job.sh
/tmp/job.sh & sleep 0.5; /tmp/job.sh     # the second copy exits immediately

# protect only part of a script: a block in a subshell
(
    flock -w 10 9 || exit 1
    echo "write to a shared file" >> /tmp/shared.log
) 9>/tmp/shared.lock

# shared lock for readers, exclusive for the writer
flock -s /tmp/data.lock cat /tmp/data.txt
flock -x /tmp/data.lock sh -c 'date > /tmp/data.txt'

# several commands under one lock
flock /tmp/a.lock -c 'echo start; sleep 1; echo end'

Pitfalls

  • Argument order with -c. File first, then -c: flock file -c '…'. Writing flock -c '…' file fails with invalid option -- 'c'.
  • Background children inherit the lock. If a script with exec 9>file starts something in the background (service &) and exits, descriptor 9 stays with the child and the lock is not released. Close the descriptor for background processes: command 9>&- &; in the wrapper form use -o.
  • Don't delete the lock file. If you delete the file while a process holds it, the next run creates a new file with a different inode and happily takes "its own" lock — the protection is gone. Just leave the file alone.
  • exec 9>file truncates the file. If the lock file stores something, open it for appending or reading: exec 9>>file or exec 9<file.
  • Locks are advisory. They only work if all participants use flock on the same file. A plain cat or echo > doesn't check the lock.
  • Without -n or -w, flock waits forever. In cron this means hung jobs pile up. For cron you almost always want -n.
  • Choose where the file lives. /tmp is cleared on reboot and is accessible to all users — someone else's process could take your lock. For system jobs /run/ or /var/lock/ is a good fit.

See also

cron · background · redirection · timeout · exit-codes