lockfile (deprecated PyPI package)

0.12.2 verified Tue May 12 auth: no python install: verified deprecated

The `lockfile` package (version 0.12.2) provides a platform-independent API for locking files across Unix and Windows, relying on atomic system calls like `link` (Unix) and `mkdir` (Windows). This package is **deprecated**, with its last release in November 2015. Users are strongly advised to use alternatives like `fasteners` or `oslo.concurrency` for file locking needs.

pip install lockfile

Common errors

error ModuleNotFoundError: No module named 'lockfile' ↓

cause The 'lockfile' package is not installed in the current Python environment.

fix

Run pip install lockfile or pip3 install lockfile. Note that the lockfile package is deprecated; consider using alternatives like fasteners or oslo.concurrency for new projects.

error ImportError: No module named lockfile.pidlockfile ↓

cause This error typically occurs when another package, such as `python-daemon`, expects a specific sub-module (`pidlockfile`) from `lockfile` that is either not installed, or there is an incompatibility with the versions of the dependent package and `lockfile`.

fix

Ensure lockfile is installed via pip install lockfile. If the error persists, try reinstalling the dependent package (e.g., python-daemon) or check its compatibility requirements. It is highly recommended to migrate to actively maintained libraries like fasteners or oslo.concurrency.

error lockfile.LockTimeout: Lock held by another process ↓

cause The `acquire()` method was called with a specified timeout, but the lock could not be obtained within that duration because another process or thread was holding the lock.

fix

You can either increase the timeout value when calling acquire(), implement a retry mechanism, or cautiously use lock.break_lock() if you are certain the existing lock is stale. For robust solutions, consider migrating to fasteners or oslo.concurrency.

error lockfile.AlreadyLocked: File is already locked ↓

cause This exception is raised when `lockfile.acquire()` is called in a non-blocking mode (e.g., with `timeout=0` or a negative value), and the file is already locked by another process or thread.

fix

Handle the AlreadyLocked exception in your code, or call acquire() without a timeout for a blocking operation, or provide a positive timeout value. It is advisable to use modern, maintained alternatives like fasteners or oslo.concurrency.

error IO error: Could not lock file ↓

cause A low-level operating system error occurred (e.g., 'Resource temporarily unavailable', errno 11) preventing `lockfile` from creating or acquiring the lock. This often indicates another process holds a conflicting lock, or there are insufficient file system permissions.

fix

Check for other processes that might be holding a lock on the target file or directory and terminate them if necessary. Verify that the Python process has appropriate read/write permissions for the directory where the lock file is created. For better reliability and features, consider switching to fasteners or oslo.concurrency.

Warnings

breaking The API underwent significant changes in version 0.9. Classes like `LinkFileLock`, `MkdirFileLock`, and `SQLiteFileLock` were moved from the top-level `lockfile` module into their own submodules (e.g., `lockfile.linklockfile.LinkFileLock`). The class naming convention also reversed, changing from `SomethingFileLock` to `SomethingLockFile`. ↓

fix Update import paths and class names to reflect the new structure (e.g., `from lockfile.linklockfile import LinkLockFile`). For backward compatibility, the old module-level definitions were retained until the 1.0 release, but direct submodule imports are recommended.

deprecated This `lockfile` package is officially deprecated and has not been updated since November 2015. It is highly recommended to migrate to actively maintained alternatives. ↓

fix Migrate to modern, actively maintained file locking libraries such as `fasteners` or `oslo.concurrency`.

gotcha The `LockFile` implementation relies on the atomic nature of `link()` on Unix and `mkdir()` on Windows. While providing cross-platform compatibility, this mechanism might not be suitable for all network file systems (e.g., NFS), where atomic guarantees can be an issue. ↓

fix For applications requiring robust locking over network file systems, consider alternatives explicitly designed for such environments or more advanced coordination primitives. For instance, `flufl.lock` is noted as NFS-safe for POSIX systems.

gotcha Calling `release()` on an already unlocked `LockFile` instance will raise a `LockError`. This can occur if the lock is released prematurely or if there's a logic error in handling lock states, particularly in complex multi-process scenarios or when mixing explicit `acquire`/`release` with context managers. ↓

fix Ensure `release()` is only called when the lock is known to be held. Using the `with` statement for `LockFile` instances is the safest approach, as it automatically handles acquisition and release, reducing the chance of `LockError` from manual management. If manual control is necessary, check `lock.is_locked()` before calling `release()`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 17.9M

3.10 alpine (musl) - - 0.01s 17.9M

3.10 slim (glibc) wheel 1.5s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.02s 19.7M

3.11 alpine (musl) - - 0.02s 19.7M

3.11 slim (glibc) wheel 1.5s 0.01s 20M

3.11 slim (glibc) - - 0.01s 20M

3.12 alpine (musl) wheel - 0.01s 11.6M

3.12 alpine (musl) - - 0.02s 11.6M

3.12 slim (glibc) wheel 1.4s 0.01s 12M

3.12 slim (glibc) - - 0.01s 12M

3.13 alpine (musl) wheel - 0.01s 11.3M

3.13 alpine (musl) - - 0.01s 11.2M

3.13 slim (glibc) wheel 1.4s 0.01s 12M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) wheel - 0.01s 17.4M

3.9 alpine (musl) - - 0.01s 17.4M

3.9 slim (glibc) wheel 1.8s 0.01s 18M

3.9 slim (glibc) - - 0.01s 18M

Imports

LockFile
wrong
```
import lockfile
```
correct
```
from lockfile import LockFile
```
While 'import lockfile' works, accessing LockFile directly from the top-level package is the common pattern.
LinkFileLock
wrong
```
from lockfile import LinkFileLock
```
correct
```
from lockfile.linklockfile import LinkFileLock
```
As of version 0.9, classes like LinkFileLock were moved into submodules, though the old top-level import was retained for backward compatibility until 1.0.
MkdirFileLock
wrong
```
from lockfile import MkdirFileLock
```
correct
```
from lockfile.mkdirlockfile import MkdirFileLock
```
Similar to LinkFileLock, MkdirFileLock was moved to a submodule in version 0.9.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to acquire and release a file lock using `LockFile`. It includes a timeout mechanism and proper error handling for when the lock cannot be acquired or is already held. The `os.environ.get` is used for the lock file path for potential external configuration.

from lockfile import LockFile
import os

lock_path = os.environ.get('LOCK_FILE_PATH', 'my_app.lock')
lock = LockFile(lock_path)

try:
    print(f"Attempting to acquire lock for {lock.path}...")
    lock.acquire(timeout=10) # Wait up to 10 seconds
    print(f"Lock acquired for {lock.path}. Performing critical operation...")
    # Simulate work
    with open('shared_resource.txt', 'a') as f:
        f.write('Critical operation performed.\n')
    print("Critical operation complete.")
except lock.AlreadyLocked: # Using lock.AlreadyLocked for consistency across versions
    print(f"Could not acquire lock for {lock.path}: Already locked by another process.")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if lock.is_locked():
        lock.release()
        print(f"Lock released for {lock.path}.")
    else:
        print(f"Lock was not acquired, so no release needed for {lock.path}.")