portalocker
Cross-platform file locking, with Redis, PID-file and bounded-semaphore locks
Decision gist · record as of 2026-08-14
Yes. Portalocker is a stable, actively maintained library with zero known vulnerabilities, low install friction, and no mandatory dependencies. It solves a real cross-platform problem (file locking) with a clean API. Install it if you need file or process coordination; the optional extras (pywin32, redis) are only required for specific lock types.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.10 or later.
- Shared locks on Windows require optional pywin32 dependency; exclusive locks work without it.
- Low friction installation with no mandatory runtime dependencies.
License · maintenance · safety
BSD-3-Clause (permissive) — BSD-3-Clause is a permissive license allowing commercial and private use with minimal restrictions, requiring only license and copyright notice preservation.
last release 2026-08-02 (12 days) · last repo commit 2026-08-06 · 325 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 65,125,508 downloads/mo, #489 on PyPI
Alternatives
Verify before relying
pip install portalocker
import portalocker
with portalocker.Lock('somefile', timeout=1) as fh:
fh.write('locked content')- Whether advisory locking on Linux/Unix is sufficient for the intended use case (mandatory locking requires special mount configuration).
- Performance characteristics under high contention or with many processes competing for the same lock.
- Behavior and reliability of Redis locks in network-partitioned or high-latency scenarios.
What it is and what it does
Portalocker is a mature file-locking library that abstracts platform differences across Windows, Linux, macOS, and Unix systems. It provides three main locking mechanisms: file-based locks (exclusive or shared), PID file locks for singleton process enforcement, and Redis-backed distributed locks for multi-process or multi-machine coordination. The library uses context managers for clean resource management and offers both high-level convenience APIs and lower-level control for custom scenarios.
The core use case is preventing concurrent access to shared resources—cache files, configuration, or work queues—across processes or machines. On Windows, exclusive locks use the built-in msvcrt module; shared locks require the optional pywin32 extra. On POSIX systems, locks are advisory by default (processes must cooperate to respect them). Redis locks are particularly useful when processes run on different machines and need reliable, network-aware synchronization.
Use it for
- Prevent multiple cache-generation scripts from running simultaneously and corrupting shared data.
- Implement singleton worker processes using PID file locks to ensure only one instance runs at a time.
- Coordinate file access across distributed services using Redis-backed locks without polling or timeout races.
- Protect configuration file updates from concurrent modification by multiple processes.
- Implement bounded semaphores across multiple processes to limit concurrent resource consumption.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
Portalocker is a stable, actively maintained library with zero known vulnerabilities, low install friction, and no mandatory dependencies. It solves a real cross-platform problem (file locking) with a clean API. Install it if you need file or process coordination; the optional extras (pywin32, redis) are only required for specific lock types.
Install
portalocker on PyPI
Before you install
Low friction installation with no mandatory runtime dependencies. The package is actively maintained with a recent release and clean commit history. Optional extras (pywin32 for Windows shared locks, redis for distributed locking) are available but not required for basic use.
Requires Python 3.10 or later. Shared locks on Windows require optional pywin32 dependency; exclusive locks work without it.
License in practice
BSD-3-Clause is a permissive license allowing commercial and private use with minimal restrictions, requiring only license and copyright notice preservation.
Quickstart
pip install portalocker
import portalocker
with portalocker.Lock('somefile', timeout=1) as fh:
fh.write('locked content')Verify before relying
- Whether advisory locking on Linux/Unix is sufficient for the intended use case (mandatory locking requires special mount configuration).
- Performance characteristics under high contention or with many processes competing for the same lock.
- Behavior and reliability of Redis locks in network-partitioned or high-latency scenarios.
Package facts
| License | BSD-3-Clause permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Actively maintained 12 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 65,125,508 / month, #489 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 6 - MatureIntended Audience :: DevelopersIntended Audience :: Information TechnologyIntended Audience :: System AdministratorsNatural Language :: EnglishOperating System :: MacOSOperating System :: MacOS :: MacOS XOperating System :: MicrosoftOperating System :: Microsoft :: WindowsOperating System :: POSIXOperating System :: POSIX :: BSDOperating System :: POSIX :: BSD :: FreeBSDOperating System :: POSIX :: BSD :: NetBSDOperating System :: POSIX :: BSD :: OpenBSDOperating System :: POSIX :: LinuxOperating System :: POSIX :: SunOS/SolarisOperating System :: UnixProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: ImplementationProgramming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPyTopic :: Software Development :: LibrariesTopic :: Software Development :: Libraries :: Python ModulesTopic :: SystemTopic :: System :: Distributed ComputingTopic :: System :: FilesystemsTopic :: System :: MonitoringTyping :: Typed |
Evidence: portalocker-4.1.0-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “pid file lock”
- portalockerPortalocker provides cross-platform file locking with support for…
- pidManages process ID files with stale detection, file locking, and…
- daemonizeDaemonize provides a Python library for converting regular Python…
Give your agent the search over MCP, or paste the wish link into any chat.
More Libraries packages
urllib3 is an HTTP client library that provides thread-safe connection pooling, SSL/TLS verification, multipart file uploads, request retries, compression support, and proxy handling for Python applications.
Requests is a Python HTTP library that simplifies sending HTTP/1.1 requests with automatic handling of headers, authentication, cookies, and response parsing.
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
Provides parsing, arithmetic, and recurrence rule computation for dates and times, with timezone support and iCalendar RFC compliance.
Install it if you need to parse flexible date strings, compute relative dates, handle timezones, or work with recurrence rules—it's the de facto choice for these tasks.
Six provides utility functions to write Python code that runs on both Python 2.7 and Python 3.3+, smoothing over language differences between the two versions.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
See also fasteners · locket · zc.lockfile · pid · redlock-py · flufl.lock · filelock · redlock · aiorwlock · python-redis-lock