{"id":272,"library":"filelock","title":"filelock","description":"filelock is a platform-independent file locking library for Python that provides inter-process synchronization via OS-level primitives (fcntl on Unix, msvcrt on Windows) with automatic fallback to soft (file-existence) locking. It supports exclusive locks (FileLock, SoftFileLock), SQLite-backed read-write locks (ReadWriteLock, added in 3.21.0), and async variants (AsyncFileLock, AsyncReadWriteLock, added in 3.25.0). The current stable version is 3.25.2, released March 2026; the project ships multiple releases per month and requires Python ≥ 3.10.","status":"active","version":"3.25.2","language":"python","source_language":"en","source_url":"https://github.com/tox-dev/filelock","tags":["file-locking","ipc","concurrency","cross-platform","async","threading","multiprocessing"],"install":[{"cmd":"pip install filelock","lang":"bash","label":"pip"}],"dependencies":[],"imports":[{"note":"Named import is idiomatic; module-level access still works but is verbose and was the old py-filelock style.","wrong":"import filelock; filelock.FileLock(...)","symbol":"FileLock","correct":"from filelock import FileLock"},{"note":"Always catch filelock.Timeout (not built-in TimeoutError) when using acquire(timeout=N).","symbol":"Timeout","correct":"from filelock import Timeout"},{"note":"Use instead of FileLock on network/FUSE mounts where fcntl is unavailable; since 3.24.0 FileLock auto-falls back on ENOSYS.","symbol":"SoftFileLock","correct":"from filelock import SoftFileLock"},{"note":"SQLite-backed multi-reader/single-writer lock added in 3.21.0. Lock file must use a .db extension.","symbol":"ReadWriteLock","correct":"from filelock import ReadWriteLock"},{"note":"Async variant; runs blocking I/O in a thread-pool executor. Use 'async with lock:' not 'with lock:'.","symbol":"AsyncFileLock","correct":"from filelock import AsyncFileLock"},{"note":"Added in 3.25.0. Wraps ReadWriteLock for asyncio; all SQLite ops dispatched to loop.run_in_executor().","symbol":"AsyncReadWriteLock","correct":"from filelock import AsyncReadWriteLock"}],"quickstart":{"code":"from filelock import FileLock, Timeout\n\n# Always lock a *separate* .lock file, not the file you intend to write.\nlock = FileLock(\"data.txt.lock\", timeout=10)\n\ntry:\n    with lock:\n        with open(\"data.txt\", \"a\") as f:\n            f.write(\"safe write\\n\")\nexcept Timeout:\n    print(\"Could not acquire lock within 10 seconds\")\n\n# Reentrant: acquiring the same lock object again inside the block is safe.\nwith lock:\n    with lock:  # internal counter incremented; no deadlock\n        pass\n","lang":"python","description":"Exclusive file lock with timeout; catch Timeout on contention."},"warnings":[{"fix":"Upgrade to Python 3.10+. Pin filelock<3.12 only if you must stay on Python 3.8/3.9 (unsupported path).","message":"Python < 3.10 is no longer supported as of filelock 3.x modern releases. The requires-python constraint is >=3.10.","severity":"breaking","affected_versions":"<3.10 (Python runtime)"},{"fix":"Use a path like 'myfile.txt.lock' and open 'myfile.txt' only inside the lock context.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass timeout=-1 explicitly for infinite wait; pass a positive float for a real deadline; catch filelock.Timeout, not TimeoutError.","message":"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'.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all (stale detection: >=3.22.0 on Unix, not Windows)"},{"fix":"Use: ReadWriteLock('myresource.db') not ReadWriteLock('myresource.lock').","message":"ReadWriteLock requires the lock file path to use a .db extension (it is backed by SQLite). Passing a plain .lock path raises an error.","severity":"breaking","affected_versions":">=3.21.0"},{"fix":"Release the lock fully before re-acquiring in a different mode.","message":"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.","severity":"gotcha","affected_versions":">=3.21.0"},{"fix":"Use poll_interval=0.05 (or your preferred float) in acquire() calls.","message":"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.","severity":"deprecated","affected_versions":">=3.x"}],"env_vars":null,"search_vec":"'2026':72 '3.10':83 '3.21.0':55 '3.25.0':63 '3.25.2':69 'ad':53,61 'async':57,92 'asyncfilelock':59 'asyncreadwritelock':60 'automat':31 'back':47 'concurr':88 'cross':90 'cross-platform':89 'current':65 'exclus':41 'exist':37 'fallback':32 'fcntl':24 'file':8,36,85 'file-exist':35 'file-lock':84 'filelock':1,2,43 'independ':7 'inter':16 'inter-process':15 'ipc':87 'level':22 'librari':10 'lock':9,38,42,51,86 'march':71 'month':79 'msvcrt':27 'multipl':76 'multiprocess':94 'os':21 'os-level':20 'per':78 'platform':6,91 'platform-independ':5 'primit':23 'process':17 'project':74 'provid':14 'python':12,82 'read':49 'read-writ':48 'readwritelock':52 'releas':70,77 'requir':81 'ship':75 'soft':34 'softfilelock':44 'sqlite':46 'sqlite-back':45 'stabl':66 'support':40 'synchron':18 'thread':93 'unix':26 'variant':58 'version':67 'via':19 'window':29 'write':50","created_at":"2026-03-28T05:38:09.270399+00:00","updated_at":"2026-04-16T15:01:24.856135+00:00","problems":[{"fix":"Install the `filelock` library using pip: `pip install filelock`","cause":"The `filelock` package is not installed in the Python environment being used.","error":"ModuleNotFoundError: No module named 'filelock'"},{"fix":"Upgrade `filelock` to the latest version (`pip install --upgrade filelock`) or, if the problem persists, try downgrading to a known stable version that is compatible with your other dependencies (e.g., `pip install filelock==3.19.1` if a newer version is causing the issue). Ensure all related packages are also up to date.","cause":"This error often occurs due to a breaking change in the `filelock` library's internal API between versions, where an internal attribute like `_thread_lock` or `_lock_file` was removed or renamed.","error":"AttributeError: 'FileLock' object has no attribute '_thread_lock'"},{"fix":"Increase the `timeout` value when creating the `FileLock` object or implement retry logic with a backoff strategy. Alternatively, ensure that processes holding the lock release it promptly.","cause":"The lock could not be acquired within the specified `timeout` period, meaning another process held the lock for too long.","error":"filelock.Timeout"},{"fix":"Use `SoftFileLock` instead of `FileLock`, as `SoftFileLock` relies on file existence (a soft lock) which is more portable across various filesystems, including network mounts: `from filelock import SoftFileLock; lock = SoftFileLock('my_file.lock')`","cause":"The underlying operating system or filesystem (e.g., some network file systems) does not support the `fcntl.flock` system call used by the default `FileLock` for hard locking.","error":"NotImplementedError: FileSystem does not appear to support flock; user SoftFileLock instead"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"3.29.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/tox-dev/py-filelock","docs":"https://py-filelock.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/filelock/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}