Coordinate access. Keep your code simple.
Portalocker provides file locks for Python on Linux, macOS and Windows. Use a context manager to coordinate access between processes, a semaphore to limit concurrent workers, or a Redis lock to coordinate across machines. Python 3.10 or later is required.
Get started | Choose a lock | API reference | Changelog
Install
python -m pip install portalocker
Exclusive file locks work without extra dependencies. Install the optional
redis extra for Redis locks, or win32 for shared file locks on Windows:
python -m pip install "portalocker[redis]"
python -m pip install "portalocker[win32]"
Redis locks need a Redis server. Shared file locks on Windows without pywin32
raise an ImportError explaining which extra to install.
Start with a file lock
Use the file handle inside the context:
import portalocker
with portalocker.Lock('report.txt', 'a', timeout=5) as fh:
fh.write('Report complete.\n')
Lock waits up to five seconds to acquire the lock. Leaving the context
releases the lock and closes the file, including when the body raises an
exception. Give every participating process the same file path.
When another holder prevents acquisition, AlreadyLocked lets you handle
contention separately from other failures:
import portalocker
with portalocker.Lock('worker.lock', 'a', timeout=1):
try:
with portalocker.Lock('worker.lock', 'a', timeout=0):
print('The second holder entered.')
except portalocker.AlreadyLocked:
print('The first holder still owns the lock.')
with portalocker.Lock('worker.lock', 'a', timeout=0):
print('The lock is available after release.')
The second lock cannot enter while the first is held. Once the outer context exits, a new holder can acquire it. This example uses the default file-locking backend. See platform behaviour before choosing a different POSIX locking primitive.
Choose a lock
| Your task | Lock | Guide |
|---|---|---|
| Coordinate access to a file | Lock |
File locking |
| Acquire again through the same lock instance | RLock |
Reentrant locks |
| Limit the number of concurrent workers | NamedBoundedSemaphore |
Workers and slots |
| Inspect a worker PID or run a singleton | PidFileLock |
PID files |
| Coordinate processes across machines | RedisLock |
Redis locks |
Give cooperating semaphores the same explicit name and directory. Keep
their slot files in a directory that will survive while workers hold them.
Locking details that matter
- Unix file locks are advisory. Every participating process must acquire a lock to honour them. Linux removed its old mandatory locking feature in kernel 5.15.
- Network filesystems have their own locking and buffering behaviour. You may
need
fh.flush()followed byos.fsync(fh.fileno())before releasing a lock. Read the platform guide and test on the filesystem you deploy to. - A
PidFileLockcontext is for inspection by default. Its body runs even when another process holds the lock, returning that holder's PID.Nonemeans this process acquired it. An unreadable or corrupt PID for a held lock raisesAlreadyLocked. Usefail_closed()when the body must only run after acquisition. See the PID examples. - A Redis lock uses a pub/sub subscription. Redis releases ownership when it
removes the subscription. Detecting a broken connection or a network
partition can take time, and the holder observes loss separately. The
Redis guide
covers
lost,ensure_held(), health checks and optional fencing tokens. Fencing only protects writes when the resource checks the token.
For single-file vendoring, see the CLI guide. For upgrades from 3.x, see the migration guide.
Contributing
Portalocker is maintained by Rick van Hattem. Bug reports and feature requests and patches are welcome. See the contribution guide for development and test commands.
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
Support
portalocker is maintained by Rick van Hattem in his own time. Most of that time goes on the platforms you are not running, so the lock behaves the same on Windows, BSD and NFS as it does on your laptop.
If it saved you an afternoon, a tip covers an hour of issue triage: Ko-fi or GitHub Sponsors.
If your company funds its dependencies, this package is on thanks.dev.
Licence
Portalocker is distributed under the BSD 3-Clause licence. See LICENSE.
2 maintainers
Metadata
2 maintainers
Release files for portalocker 4.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| portalocker-4.4.1.tar.gz | 310.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| portalocker-4.4.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 440.3 kB
Release files / portalocker-4.4.1.tar.gz
| Download URL | portalocker-4.4.1.tar.gz |
|---|---|
| Size | 310.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
42fcacc417a91b9b90238ae70fa7a3955d7a8b1e93866cc4cd830034895e10f0
|
|
BLAKE2b-256 checksum How to use checksums |
bb931f6aa8f60afaf20f0519255f7cade308d774010550c26779cf54439f0b91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / portalocker-4.4.1-py3-none-any.whl
| Download URL | portalocker-4.4.1-py3-none-any.whl |
|---|---|
| Size | 129.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4a184e8fb1adb37e078ca1804f1b7c0d8e73d81136790b1ad695ae8f1c8be291
|
|
BLAKE2b-256 checksum How to use checksums |
47ec02e439b10c6b2aa26629f269a27ae2aa395fae70207fd344046858a34156
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency log
