filelock

Warnings

• breaking Python < 3.10 is no longer supported as of filelock 3.x modern releases. The requires-python constraint is >=3.10.
  Fix: Upgrade to Python 3.10+. Pin filelock<3.12 only if you must stay on Python 3.8/3.9 (unsupported path).
• gotcha Never lock the file you intend to write; create a separate companion .lock file. Locking the target file directly causes undefined behaviour because filelock may truncate or interfere with it.
  Fix: Use a path like 'myfile.txt.lock' and open 'myfile.txt' only inside the lock context.
• gotcha Timeout=None (the default) and timeout=-1 both mean 'block forever'. A timeout of 0 means exactly one non-blocking attempt. Passing timeout=0 does NOT mean 'no timeout'.
  Fix: Pass timeout=-1 explicitly for infinite wait; pass a positive float for a real deadline; catch filelock.Timeout, not TimeoutError.
• gotcha SoftFileLock can leave stale lock files if a process crashes. On network/FUSE mounts where fcntl is unsupported, FileLock silently falls back to SoftFileLock (since 3.24.0), which is only stale-safe on same-host contention.
  Fix: For cross-host NFS/FUSE use-cases, rely on SoftFileLock's built-in PID+hostname stale detection (>=3.22.0) and set a sensible timeout.
• breaking ReadWriteLock requires the lock file path to use a .db extension (it is backed by SQLite). Passing a plain .lock path raises an error.
  Fix: Use: ReadWriteLock('myresource.db') not ReadWriteLock('myresource.lock').
• gotcha ReadWriteLock upgrading or downgrading lock mode (read→write or write→read) within the same thread raises RuntimeError. The lock is reentrant only within the same mode.
  Fix: Release the lock fully before re-acquiring in a different mode.
• deprecated The poll_intervall parameter (double-l spelling) in acquire() is deprecated in favour of poll_interval (single-l). Both are accepted for backward compatibility but the old spelling will eventually be removed.
  Fix: Use poll_interval=0.05 (or your preferred float) in acquire() calls.

Install

• pip install filelock pip

Imports

• FileLock

  from filelock import FileLock

  Named import is idiomatic; module-level access still works but is verbose and was the old py-filelock style.
• Timeout

  from filelock import Timeout

  Always catch filelock.Timeout (not built-in TimeoutError) when using acquire(timeout=N).
• SoftFileLock

  from filelock import SoftFileLock

  Use instead of FileLock on network/FUSE mounts where fcntl is unavailable; since 3.24.0 FileLock auto-falls back on ENOSYS.
• ReadWriteLock

  from filelock import ReadWriteLock

  SQLite-backed multi-reader/single-writer lock added in 3.21.0. Lock file must use a .db extension.
• AsyncFileLock

  from filelock import AsyncFileLock

  Async variant; runs blocking I/O in a thread-pool executor. Use 'async with lock:' not 'with lock:'.
• AsyncReadWriteLock

  from filelock import AsyncReadWriteLock

  Added in 3.25.0. Wraps ReadWriteLock for asyncio; all SQLite ops dispatched to loop.run_in_executor().

Quickstart

Exclusive file lock with timeout; catch Timeout on contention.

from filelock import FileLock, Timeout

# Always lock a *separate* .lock file, not the file you intend to write.
lock = FileLock("data.txt.lock", timeout=10)

try:
    with lock:
        with open("data.txt", "a") as f:
            f.write("safe write\n")
except Timeout:
    print("Could not acquire lock within 10 seconds")

# Reentrant: acquiring the same lock object again inside the block is safe.
with lock:
    with lock:  # internal counter incremented; no deadlock
        pass