Introduction

File locking prevents multiple processes from stepping on the same file at the same time. In Python, the right approach depends on your operating system, because Unix and Windows use different locking APIs and most locks are advisory rather than magically enforced by the filesystem itself.

Advisory Locks Versus Mandatory Behavior

The first concept to understand is that file locks are usually advisory. That means cooperating processes must also use the locking protocol. If one process ignores it and writes directly, the OS may still allow the write.

So locking works well when:

• your own processes all respect the lock
• your application controls the read and write paths
• you want to serialize file updates safely

It is not a perfect defense against arbitrary external processes.

Unix Example With fcntl.flock

On Unix-like systems, fcntl.flock() is the common tool.

1import fcntl
2
3with open("data.txt", "a+") as f:
4    fcntl.flock(f, fcntl.LOCK_EX)
5    try:
6        f.write("safe write\n")
7        f.flush()
8    finally:
9        fcntl.flock(f, fcntl.LOCK_UN)

LOCK_EX means an exclusive lock. Only one cooperating process should hold it at a time. If you only need shared read access, use LOCK_SH.

To fail immediately instead of waiting, combine with LOCK_NB:

fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB)

Then catch BlockingIOError if another process already holds the lock.

Windows Has A Different API

On Windows, fcntl is not available. One option is msvcrt.locking(), though many Python developers choose a cross-platform third-party library instead because the platform-specific details are awkward.

That is an important design point: if your code must run on both Unix and Windows, a portability wrapper is often worth it.

A Cross-Platform Option With filelock

The filelock package is simple and widely used. It creates a separate lock file and works across platforms.

1from filelock import FileLock
2
3lock = FileLock("data.txt.lock", timeout=10)
4
5with lock:
6    with open("data.txt", "a", encoding="utf-8") as f:
7        f.write("safe write\n")

This is often the most practical answer for application code because it avoids platform branching and keeps the locking logic explicit.

Pick The Right Locking Strategy

There are two common patterns:

• lock the target file directly
• lock a separate companion file such as data.txt.lock

A separate lock file is easier to reason about in many scripts and services. Direct file locking is closer to the underlying resource, but it may be less portable depending on your API choices.

Timeouts And Retries

Lock acquisition can block. Decide what your application should do when the file is busy:

• wait until the lock is free
• fail fast
• retry with backoff

A simple retry loop looks like this:

1import time
2from filelock import FileLock, Timeout
3
4lock = FileLock("data.txt.lock", timeout=1)
5
6for _ in range(5):
7    try:
8        with lock:
9            print("lock acquired")
10            break
11    except Timeout:
12        time.sleep(0.5)
13else:
14    raise RuntimeError("Could not acquire lock")

This is useful in batch jobs or worker processes where short contention bursts are normal.

Locking Does Not Replace Flush And Sync

Locking controls concurrency, but it does not automatically guarantee durable writes. If durability matters, flush the file and consider os.fsync() after writing.

1import os
2import fcntl
3
4with open("data.txt", "a") as f:
5    fcntl.flock(f, fcntl.LOCK_EX)
6    try:
7        f.write("important record\n")
8        f.flush()
9        os.fsync(f.fileno())
10    finally:
11        fcntl.flock(f, fcntl.LOCK_UN)

That distinction matters for logs, ledgers, and job state files.

Common Pitfalls

• Assuming file locks are mandatory for every process on the machine.
• Forgetting that Unix and Windows use different APIs.
• Locking the file but writing through a separate path that does not respect the lock.
• Holding the lock longer than necessary, which increases contention.
• Forgetting to flush or sync when write durability matters.

Summary

• File locking in Python is mainly about coordinating cooperating processes.
• Use fcntl.flock() on Unix-like systems for direct file locks.
• Use a library such as filelock for a simpler cross-platform solution.
• Decide whether your application should block, fail fast, or retry when a lock is busy.
• Locking prevents concurrent access problems, but it does not automatically make writes durable.