Installer

0.7.0 · active · verified Sat Mar 28

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.

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

pip install installer Install stable release

Imports

install
```
from installer import install
```

SchemeDictionaryDestination

from installer.destinations import SchemeDictionaryDestination

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

Quickstart

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.")

view raw JSON →