Registry / devops / installer

installer

JSON →
library0.7.0pypypi✓ verified 52d ago

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.

devops
pip install installer
Install & Compatibility
Where this runs
tested against v1.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.925 runs
installs and imports cleanly · install 0.0s · import 0.242s · 18.8MB
glibc
py 3.103.925 runs
installs and imports cleanly · install 1.6s · import 0.212s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

install
from installer import install
SchemeDictionaryDestination
from installer.destinations import SchemeDictionaryDestination
WheelFile
from installer.sources import WheelFile

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.")
Debug
Known issues
breakingVersion 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`.
affects: >=0.5.0
breakingIn 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`.
affects: >=0.2.1
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`.
affects: all
gotchaThe 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.
affects: <0.2.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'installer'
The 'installer' library has not been installed in your Python environment.
fix
Install the library using pip: `pip install installer`
FileExistsError: [Errno 17] File exists: '...' during reinstallation or update
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.
ValueError: ... (related to wheel format or metadata parsing)
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.
Upgrade
Version history
1.0.1latest on PyPI
Audit
Dependencies
wheelrequiredRequired for working with .whl files, specifically the `WheelFile.open` functionality.
Agent activity
12 hits · last 30 days
node
4
seranking-bot
4
ahrefsbot
3
Resources