patchelf-wrapper

Common errors

• patchelf: command not found

  cause The `patchelf` binary, installed by `patchelf-wrapper`, is not in your system's PATH, or `patchelf-wrapper` failed to install it correctly.
  fix Ensure `patchelf-wrapper` was installed successfully. If using a virtual environment, ensure it's activated. You can programmatically find the path using `from patchelf_wrapper.patchelf import find_patchelf_cmd`.

• ERROR: Could not find a version that satisfies the requirement patchelf-wrapper (from versions: none)
  ERROR: No matching distribution found for patchelf-wrapper

  cause This typically indicates an issue with `pip` resolving dependencies, network connectivity, or incompatible Python/packaging environments, often seen when `pip` subprocesses fail during backend dependency installation.
  fix Check your network connection. Ensure your `pip` and `setuptools` are up-to-date (`pip install --upgrade pip setuptools`). If building from source, verify `pyproject.toml` or `setup.py` requirements. Consider using `--no-build-isolation` with `pip install` in some build systems.

• patchelf: ELF file header not found

  cause The file provided to `patchelf` is not a valid ELF executable or library.
  fix Verify that the target file is indeed an ELF binary. Use `file <filename>` on Linux to check its type. Ensure the path to the file is correct and accessible.

• patchelf: not an ELF executable

  cause Similar to 'ELF file header not found', this error means the specified file is not recognized as a valid ELF executable that `patchelf` can operate on.
  fix Double-check the target file. `patchelf` can only modify ELF (Executable and Linkable Format) files commonly found on Linux/Unix systems. It cannot modify Windows executables (PE files) or macOS executables (Mach-O files).

Warnings

• gotcha The project's author explicitly recommends installing `patchelf` through your operating system's package manager rather than using `patchelf-wrapper` for general end-user needs, as the wrapper is primarily for PyPI-hosted projects requiring `patchelf` as a build dependency.
  Fix: For end-users, prefer `sudo apt-get install patchelf` (Debian/Ubuntu) or `sudo dnf install patchelf` (Fedora/RedHat/CentOS), etc.
• gotcha `patchelf-wrapper` currently installs `patchelf` version 0.11. A separate, official `patchelf` package on PyPI (`pip install patchelf`) offers version 0.17.2.4 (as of July 2025), and system package managers often provide newer versions than 0.11. This version discrepancy can lead to missing features or unexpected behavior if a project expects a more recent `patchelf` utility.
  Fix: Verify the `patchelf` version installed by `patchelf-wrapper`. If a newer version is required, consider using the direct `patchelf` PyPI package or system-level installation. Ensure compatibility if integrating into a build process.
• gotcha Earlier versions (e.g., v1.0.2, v1.0.3, v1.0.4, v0.2.0) had installation issues with `bdist_egg`, `python setup.py install`, and very old versions of `setuptools`. These issues have been fixed in more recent `patchelf-wrapper` releases.
  Fix: Ensure you are using `patchelf-wrapper` version 1.1.0 or newer and have an up-to-date `setuptools` package to avoid installation problems.
• breaking The underlying `patchelf` utility, which this wrapper provides, has historically had bugs that could lead to binary corruption with certain operations, such as `--set-soname` or when run multiple times on the same binary, especially with older versions of `patchelf`.
  Fix: Always back up ELF binaries before modifying them. Test `patchelf` operations thoroughly in a controlled environment. For critical or complex ELF modifications, consult the `patchelf` changelog for known issues or consider alternative libraries like LIEF for programmatic ELF manipulation.

Install

• pip install patchelf-wrapper Install latest version

Imports

• find_patchelf_cmd

  from patchelf_wrapper.patchelf import find_patchelf_cmd

  This function is used to locate the installed `patchelf` binary. The `patchelf` utility itself is primarily designed to be invoked as a subprocess command, not through an extensive Python API.

Quickstart

This quickstart demonstrates how to locate the `patchelf` binary installed by `patchelf-wrapper` and then execute it via `subprocess` to perform common operations like printing its version or an ELF binary's RPATH.

import subprocess
from patchelf_wrapper.patchelf import find_patchelf_cmd

try:
    patchelf_path = find_patchelf_cmd()
    print(f"Found patchelf at: {patchelf_path}")

    # Example: Print the version of the installed patchelf
    result = subprocess.run([patchelf_path, '--version'], capture_output=True, text=True, check=True)
    print("patchelf version:\n", result.stdout.strip())

    # Example: Print RPATH of an ELF binary (replace 'your_binary' with an actual path)
    # It's important to use a real ELF file for this, or it will error.
    # try:
    #     some_elf_binary = "/bin/ls" # Replace with a test ELF binary path
    #     rpath_result = subprocess.run([patchelf_path, '--print-rpath', some_elf_binary], capture_output=True, text=True, check=True)
    #     print(f"RPATH of {some_elf_binary}: {rpath_result.stdout.strip()}")
    # except FileNotFoundError:
    #     print(f"Warning: Could not find '{some_elf_binary}' to demonstrate RPATH printing.")
    # except subprocess.CalledProcessError as e:
    #     print(f"Error running patchelf on {some_elf_binary}: {e.stderr.strip()}")

except RuntimeError as e:
    print(f"Error: {e}")
except FileNotFoundError:
    print("Error: patchelf binary not found. Ensure patchelf-wrapper is correctly installed.")