lefthook

library2.1.6pypypiunverified

Lefthook is a fast, powerful, and simple Git hooks manager. Written in Go, it streamlines development workflows by automating tasks like linting and testing during Git operations. It is actively maintained with frequent releases, currently at version 2.1.6, often seeing updates on a monthly or bi-monthly cadence.

devops

pip install lefthook

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LEFTHOOK

lefthook

devopspythonv2.1.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

After installing, create a `lefthook.yml` file in your project root to define hooks. Then, run `lefthook install` to set up the Git hooks. The provided `lefthook.yml` snippet demonstrates a `pre-commit` hook that runs `flake8` for linting and `black` for formatting on staged Python files, automatically staging `black`'s fixes. Lefthook runs commands in parallel by default, improving efficiency.

#!/bin/bash # .github/workflows/verify-hooks.yml (example for CI) # Install lefthook (e.g., in CI or dev setup) pip install lefthook # Initialize lefthook configuration lefthook install # Example lefthook.yml content (create this file in your project root) # pre-commit: # parallel: true # commands: # lint: # glob: "*.py" # run: flake8 {staged_files} # format: # glob: "*.py" # run: black {staged_files} # stage_fixed: true # To run hooks manually (e.g., for testing): # lefthook run pre-commit

lefthook --version

Debug

Known issues

breakingVersion 2.0.0 introduced significant breaking changes. The `exclude` option no longer accepts regular expressions, only globs. The `skip_output` option was removed, replaced by `output`. Several CLI arguments were renamed for consistency.

fix

Review your `lefthook.yml` configuration and CLI usage against the v2 documentation. Update `exclude` patterns to use globs, replace `skip_output` with `output`, and adjust CLI commands as needed.

affects: >=2.0.0

gotchaOn Windows, `lefthook` commands might fail with 'Can't find lefthook in PATH', or hooks configured with `parallel: true` can hang or cause new command windows to briefly pop up. This is often related to PATH configuration or process handling specifics on Windows.

fix

Ensure the `lefthook` executable's directory is correctly added to your system's PATH. For hanging or new window issues, try disabling `parallel: true` for problematic hooks on Windows, or explore specific `runner` configurations if applicable. Recent versions have improved Windows path normalization.

affects: All versions on Windows

gotchaRunning `git commit` or other hooks can hang indefinitely if your system loses internet connectivity, especially if `lefthook` is configured to fetch remote configurations or if `npx` is used as a fallback for command execution.

fix

Ensure `lefthook` is installed globally (e.g., via `pipx install lefthook`) rather than relying on `npx`. If remote configs are used, ensure they are cached or accessible offline, or use `LEFTHOOK=0 git commit` to bypass hooks when offline.

affects: All versions

gotchaIn certain VSCode/WSL2 setups, `lefthook` output in the Git output panel may appear unreadable due to uninterpreted ANSI color escape codes. This happens when tools output colors, but the rendering environment doesn't support them.

fix

Configure the tools used in your `lefthook` commands (e.g., linters, formatters) to output without colors. For instance, many tools support a `--no-color` or `--color=never` flag.

affects: All versions with affected terminal/IDE setups

Errors

Common errors & fixes

Can't find lefthook in PATH

The `lefthook` executable is not located in any directory listed in the system's PATH environment variable, particularly common on Windows systems after global npm installs.

fix

Manually add the directory containing the `lefthook` executable to your system's PATH. If installed via npm, this might be `%APPDATA%\npm` or similar; for pipx, it's typically `~/.local/bin` on Linux/macOS or `%USERPROFILE%\AppData\Roaming\Python\Scripts` on Windows.

Git commit hangs indefinitely / commands pop up in new window (Windows)

Lefthook's process management, especially with `parallel: true` or `sh -c` wrappers, can lead to child processes hanging or spawning new windows on Windows due to shell interaction differences.

fix

Disable `parallel: true` for the affected hooks in `lefthook.yml` when on Windows. Ensure `lefthook` is updated to the latest version for relevant fixes. Investigate specific commands that trigger the issue and adjust their execution or use `no_tty: true` in `lefthook.yml` as a potential workaround if applicable.

Git commit hangs indefinitely when internet connection is unavailable

Lefthook might attempt to access network resources (e.g., update its binary, fetch remote configurations, or use `npx` for fallback command execution) and get stuck if the internet is not available.

fix

Ensure `lefthook` is installed locally via pip/pipx rather than relying on `npx` in hooks. If you have remote configs, manage them carefully. As a temporary workaround, prepend `LEFTHOOK=0` to your `git commit` command (e.g., `LEFTHOOK=0 git commit -m "fix"`) to bypass hooks.

Lefthook git output with ESC characters is unreadable in VSCode

When `lefthook` runs commands that output ANSI color codes, and the VSCode Git output panel or integrated terminal in WSL2 doesn't interpret these codes, they appear as raw escape sequences.

fix

Modify the commands in your `lefthook.yml` to explicitly disable colored output. For example, use `eslint --no-color`, `prettier --color always`, or similar options for your linters/formatters.

error getting file: exit 128 (often with pre-push hook)

This error can occur if `lefthook` is unable to resolve Git HEAD, often when a local branch is not tracking a remote branch, or if there's a misconfigured `glob` pattern in `lefthook.yml` that doesn't match any files.

fix

Ensure your local branch is tracking an upstream branch (e.g., `git push -u origin your-branch`). Double-check the `glob` patterns in your `lefthook.yml` to ensure they correctly identify files for the intended commands.

Upgrade

Version history

2.1.6latest on PyPI · released Apr 16, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/evilmartians/lefthook ↗

packagehttps://pypi.org/project/lefthook/ ↗

homepagehttps://lefthook.dev ↗