{"id":9169,"library":"patchelf-wrapper","title":"patchelf-wrapper","description":"patchelf-wrapper is a Python module designed to assist in the installation of the `patchelf` utility for PyPI-hosted Python projects that depend on it. It ensures the `patchelf` binary is available within a project's build environment. The current version, 1.2.0, packages patchelf 0.11. The project's author notes that for end-users, installing `patchelf` via a system package manager is generally recommended over this wrapper.","status":"maintenance","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/jimporter/patchelf-wrapper","tags":["ELF","binary","linker","shared library","build tool","patchelf"],"install":[{"cmd":"pip install patchelf-wrapper","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"find_patchelf_cmd","correct":"from patchelf_wrapper.patchelf import find_patchelf_cmd"}],"quickstart":{"code":"import subprocess\nfrom patchelf_wrapper.patchelf import find_patchelf_cmd\n\ntry:\n    patchelf_path = find_patchelf_cmd()\n    print(f\"Found patchelf at: {patchelf_path}\")\n\n    # Example: Print the version of the installed patchelf\n    result = subprocess.run([patchelf_path, '--version'], capture_output=True, text=True, check=True)\n    print(\"patchelf version:\\n\", result.stdout.strip())\n\n    # Example: Print RPATH of an ELF binary (replace 'your_binary' with an actual path)\n    # It's important to use a real ELF file for this, or it will error.\n    # try:\n    #     some_elf_binary = \"/bin/ls\" # Replace with a test ELF binary path\n    #     rpath_result = subprocess.run([patchelf_path, '--print-rpath', some_elf_binary], capture_output=True, text=True, check=True)\n    #     print(f\"RPATH of {some_elf_binary}: {rpath_result.stdout.strip()}\")\n    # except FileNotFoundError:\n    #     print(f\"Warning: Could not find '{some_elf_binary}' to demonstrate RPATH printing.\")\n    # except subprocess.CalledProcessError as e:\n    #     print(f\"Error running patchelf on {some_elf_binary}: {e.stderr.strip()}\")\n\nexcept RuntimeError as e:\n    print(f\"Error: {e}\")\nexcept FileNotFoundError:\n    print(\"Error: patchelf binary not found. Ensure patchelf-wrapper is correctly installed.\")","lang":"python","description":"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."},"warnings":[{"fix":"For end-users, prefer `sudo apt-get install patchelf` (Debian/Ubuntu) or `sudo dnf install patchelf` (Fedora/RedHat/CentOS), etc.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<= 1.0.4"},{"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.","message":"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`.","severity":"breaking","affected_versions":"All versions (due to underlying `patchelf` utility)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The `patchelf` binary, installed by `patchelf-wrapper`, is not in your system's PATH, or `patchelf-wrapper` failed to install it correctly.","error":"patchelf: command not found"},{"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.","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.","error":"ERROR: Could not find a version that satisfies the requirement patchelf-wrapper (from versions: none)\nERROR: No matching distribution found for patchelf-wrapper"},{"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.","cause":"The file provided to `patchelf` is not a valid ELF executable or library.","error":"patchelf: ELF file header not found"},{"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).","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.","error":"patchelf: not an ELF executable"}]}