---
id: flufl-lock
version: "9.1.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# flufl.lock — NFS-safe file locking with timeouts for POSIX and Windows

License: permissive · Maintenance: active · Downloads: 3.2M/mo

## What it is and what it does

flufl.lock is a file-based locking library that solves the race-condition problem inherent in NFS file systems by using an atomic link-based algorithm inspired by the O_EXCL flag behavior. Instead of relying on exclusive file creation (which is broken on NFS), it creates a unique temporary file and uses the link(2) system call to atomically establish the lock—a technique that works correctly across network file systems and local filesystems alike.

The library is designed for distributed and multi-process environments where you need to coordinate access to shared resources. It supports lock breaking with configurable timeouts, allowing other processes to forcibly acquire a lock if the holder exceeds its declared lifetime. This prevents permanent deadlocks but requires careful tuning: set the lifetime too long and processes will hang waiting; too short and you risk trampling on active locks and corrupting data. It runs on POSIX systems (Linux, macOS) and Windows, making it suitable for cross-platform applications that must coordinate file access.

Use it for:

- Serialize access to shared configuration or data files in a distributed system where multiple hosts mount the same NFS volume.
- Prevent concurrent writes to a shared database or log file in a multi-process web application or job queue.
- Implement a distributed task lock so only one worker process executes a critical operation across a cluster.
- Protect against race conditions in CI/CD pipelines or build systems that run on shared network storage.
- Coordinate resource access in containerized or Kubernetes environments where pods may share persistent volumes.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides NFS-safe file locking with timeout support across POSIX and Windows systems, using an atomic link-based algorithm to prevent race conditions.

Yes. This is a mature, actively maintained library with no known vulnerabilities, low install friction, and a permissive license. Install it if you need cross-platform, NFS-safe file locking with timeout support. The main consideration is tuning the lock lifetime correctly for your use case; if you're unsure whether you need NFS safety specifically, a simpler locking mechanism may suffice.

## Install

pip install flufl-lock
uv add flufl-lock
poetry add flufl-lock

## Installing flufl.lock

Before you install: Low friction installation with only two lightweight runtime dependencies (atpublic, psutil). Actively maintained with a recent release; marked Production/Stable and Mature.

License in practice: Apache-2.0 is permissive; you can use this in commercial and proprietary projects with minimal restrictions beyond attribution and liability disclaimers.

Quickstart:

from flufl.lock import Lock
lock = Lock('/tmp/mylock')
with lock:
    # critical section
    pass

Requires Python 3.10 or later; lock lifetime must be chosen carefully to balance between process hangs and data corruption risk.

Verify before relying:

- Whether clock synchronization requirements are critical in practice for typical use cases outside distributed NFS environments.
- Performance characteristics under high contention or with very short lock lifetimes.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

NFS-safe file locking, distributed file locks, atomic file locking, cross-platform lock timeout, POSIX Windows file locking, lock breaking mechanism, race-condition-free locking, distributed-locking, nfs-safe, cross-platform

[View on SkillFed](https://skillfed.io/packages/flufl-lock) · [View on PyPI](https://pypi.org/project/flufl-lock/)