pylocalauth

Cross-platform local authentication library for Python applications.

---

Documentation: README

Source Code: Repository

---

Add local authentication to your Python applications with ease. pylocalauth provides a simple and secure way to authenticate users using platform-specific methods such as passwords, biometrics, and PINs.

Features

Feature	Status
Cross-platform: Works on Windows, macOS, and Linux. (macOS is still in beta, but it should work reliably)	✅
Multiple authentication methods: Supports password-based, biometric (Windows Hello, Touch ID, etc.), and PIN-based authentication.	✅
Easy integration: Simple API for integrating local authentication into your Python applications.	✅
Secure: Utilizes platform-specific security features to ensure user data is protected.	✅
Lightweight: Minimal dependencies and easy to install.	✅

Windows Example	Linux Example

Installation

You can install pylocalauth via pip:

pip install pylocalauth --upgrade

Usage

Here's a very simple example of how to use pylocalauth to authenticate a user:

frompylocalauthimportauthenticate# Import the authenticate function for your platformresult=authenticate()
ifresult:
print("Authentication successful!")
else:
print("Authentication failed.")

You can also customize the message displayed during authentication:

frompylocalauthimportauthenticateresult=authenticate(message="Please authenticate to proceed.")

By default, pylocalauth will raise an AuthUnavailableError if authentication is not available on the current platform. You can disable this behavior by setting the check_availability parameter to False (You should only do this if you plan to handle the unavailability yourself):

frompylocalauthimportauthenticate, is_availablefrompylocalauth.exceptionsimportAuthError, AuthUnavailableError# Let it handle availability automaticallytry:
result=authenticate(check_availability=True) # defaultprint(f"Authentication successful?: {result}")
exceptAuthUnavailableError:
print("Authentication is not available on this platform.")
exceptAuthErrorase:
print(f"An error occurred: {e}")
# Handle availability yourselftry:
ifnotis_available():
print("Authentication is not available on this platform.")
else:
result=authenticate(check_availability=False)
print(f"Authentication successful?: {result}")
exceptAuthErrorase:
print(f"An error occurred: {e}")

Contributing

We welcome contributions from the community! If you'd like to contribute, please follow the steps explained in the CONTRIBUTORS file.

Contributions Needed

We are especially looking for help with the following:

• macOS support: Testing, bug reports, and improvements for the macOS backend.
• Documentation & Tests: Examples, API docs, tests (using pytest and pytest-asyncio) and usage guides.
• CI/CD: Enhancements to cross-platform test automation.
• New authentication methods: Suggestions or PRs for additional local authentication backends.
• Issue triage: Help us reproduce and resolve open issues.

If you want to help, please see CONTRIBUTORS and open an issue or pull request!

Development

Setup environment

We use Hatch to manage the development environment and production build. Ensure it's installed on your system.

Run unit tests

You can run all the tests with:

hatch run test

Format the code

Execute the following command to apply isort and black formatting:

hatch run lint

License

This project is licensed under the terms of the Apache 2.0 license. See the LICENSE file for more information.