Installer

0.7.0 verified Tue May 12 auth: no python install: verified quickstart: stale

Installer is a low-level library from the Python Packaging Authority (PyPA) designed for installing Python wheel distributions. It provides fundamental abstractions and functionality for unpacking wheels and generating platform-independent Python script wrappers. As a core PyPA tool, it is actively maintained with releases occurring as new functionality, bug fixes, or compatibility updates are needed.

pip install installer

Common errors

error ModuleNotFoundError: No module named 'installer' ↓

cause The 'installer' library has not been installed in your Python environment.

fix

Install the library using pip: pip install installer

error FileExistsError: [Errno 17] File exists: '...' during reinstallation or update ↓

cause This error occurs when the 'installer' library attempts to install a file that already exists and cannot be overwritten, often during a package reinstallation or update process.

fix

This is a known issue (e.g., pypa/installer#121) where the installer does not automatically handle existing files during reinstallation. A workaround might involve manually cleaning the target directory before installation or using higher-level tools like pip that manage uninstallation/installation more robustly. If using installer directly, ensure the destination is clean or implement a pre-uninstall step for existing files.

error ValueError: ... (related to wheel format or metadata parsing) ↓

cause The 'installer' library encountered a malformed wheel distribution or invalid metadata within the wheel, preventing it from correctly parsing or installing the package. This can happen if the wheel's internal structure (e.g., file paths, RECORD file, metadata) does not conform to PEP standards.

fix

Ensure the wheel file (.whl) you are attempting to install is correctly formatted and not corrupted. If you are building the wheel yourself, verify your build backend configuration (e.g., pyproject.toml, setup.py) adheres to Python packaging standards. If downloading, try obtaining the wheel from a trusted source or rebuilding it.

Warnings

breaking Version 0.5.0 dropped official support for Python 3.6 and earlier. Users on older Python versions must use `installer < 0.5.0`. ↓

fix Upgrade to Python 3.7+ or pin `installer` to a version `<0.5.0`.

breaking In version 0.2.1, the internal `parse_record_file` function (used for parsing .dist-info/RECORD files) was changed to yield tuples instead of `RecordEntry` objects. While this is a low-level API, custom tools directly interacting with this function might break. ↓

fix Update custom code to expect tuples `(path, hash, size)` instead of `RecordEntry` objects when using `parse_record_file`.

gotcha `installer` is a low-level library for wheel installation. It does not handle dependency resolution, environment management (like virtual environments), or fetching wheels from PyPI. Users are expected to provide a wheel file and manage the installation environment themselves. Higher-level tools like `pip` build upon `installer`'s functionality. ↓

fix Understand `installer`'s scope; for end-user package management, use tools like `pip` or `uv`.

gotcha The initial PyPI releases of `installer` (before 0.2.0) were from a different repository (`sarugaku/installer`) and have been officially yanked. Ensure you are using versions from the `pypa/installer` project to avoid confusion or compatibility issues. ↓

fix Always use `installer >= 0.2.0` which is from the official PyPA project.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.28s 18.8M

3.10 slim (glibc) - - 0.14s 19M

3.11 alpine (musl) - - 0.35s 20.7M

3.11 slim (glibc) - - 0.30s 21M

3.12 alpine (musl) - - 0.36s 12.5M

3.12 slim (glibc) - - 0.34s 13M

3.13 alpine (musl) - - 0.26s 12.2M

3.13 slim (glibc) - - 0.21s 13M

3.9 alpine (musl) - - 0.17s 18.3M

3.9 slim (glibc) - - 0.18s 19M

Imports

install
```
from installer import install
```

SchemeDictionaryDestination

from installer.destinations import SchemeDictionaryDestination

WheelFile
```
from installer.sources import WheelFile
```

Quickstart stale last tested: 2026-04-23

The quickstart demonstrates how to use `installer` to install a Python wheel (.whl) file. It involves defining a `SchemeDictionaryDestination` based on `sysconfig.get_paths()` for standard installation locations, opening a wheel file with `WheelFile.open`, and then calling the `install` function with the source and destination. This is a low-level operation requiring a wheel file path.

import sys
import sysconfig
from pathlib import Path
from installer import install
from installer.destinations import SchemeDictionaryDestination
from installer.sources import WheelFile

# NOTE: Replace 'sampleproject-1.3.1-py2.py3-none-any.whl' with a path
# to an actual wheel file you intend to install. This example assumes
# the wheel file is in the current working directory.
wheel_path = Path('./sampleproject-1.3.1-py2.py3-none-any.whl')

# Create a destination handler for installation directories.
# sysconfig.get_paths() provides standard installation paths.
# interpreter=sys.executable specifies the Python interpreter to target.
# script_kind determines the type of script wrappers (e.g., 'posix' for Linux/macOS,
# or 'windows' for Windows executable wrappers).
destination = SchemeDictionaryDestination(
    sysconfig.get_paths(),
    interpreter=sys.executable,
    script_kind="posix", # Use "posix" for Unix-like, or "windows" for Windows
)

# Open the wheel file using WheelFile.open context manager.
with WheelFile.open(wheel_path) as source:
    # Perform the installation.
    install(
        source=source,
        destination=destination,
        # Additional metadata that can be generated by the installation tool.
        additional_metadata={
            "INSTALLER": b"my-custom-installer 0.1.0",
        },
    )

print(f"Successfully attempted to install {wheel_path.name}")
print("Note: Actual installation effects depend on environment and permissions.")