ISBNlib

3.10.14 · active · verified Thu Apr 16

ISBNlib is an active Python library (current version 3.10.14) providing a pure-Python solution for extracting, cleaning, transforming, hyphenating, and fetching metadata for ISBNs (International Standard Book Numbers). It offers a straightforward API for various ISBN-related tasks and receives frequent minor updates to its internal data ranges and service integrations.

Common errors

```
ModuleNotFoundError: No module named 'isbnlib'
```
cause The `isbnlib` library is not installed in the currently active Python environment, or there are permission issues (e.g., installing as a user, but running a script as root).

fix Ensure `isbnlib` is installed in the correct environment using `pip install isbnlib`. If encountering issues on Linux with `sudo`, try `sudo pip install isbnlib` (though virtual environments are preferred).
```
isbnlib.exceptions.ISBNLibURLError: Service unavailable or network error during metadata fetch. (or similar KeyError during metadata retrieval, e.g., KeyError: '9781585109043default')
```
cause The chosen metadata service (default is Google Books, 'goob') is either temporarily down, unreachable due to network issues, or does not recognize the ISBN.

fix Check your internet connection. Try explicitly requesting metadata from a different service, such as `meta(isbn, service='openl')` or `meta(isbn, service='wiki')`.
```
`meta(isbn)` returns an empty dictionary `{}` or very sparse data.
```
cause The metadata service could not find data for the provided ISBN, or the available data is minimal. Different services specialize in different types of books or regions.

fix Experiment with various metadata services, for example, `meta(isbn, service='goob')`, `meta(isbn, service='openl')`, or `meta(isbn, service='wiki')`. Consider updating `isbnlib` to ensure you have the latest service configurations and data ranges.
```
`isbnlib.mask(isbn)` does not hyphenate a valid ISBN, or produces an unexpected output format.
```
cause The internal data ranges used by `isbnlib` to determine hyphenation points might be outdated for recently issued ISBNs.

fix Update `isbnlib` to the latest version (`pip install --upgrade isbnlib`) to ensure the most current ISBN data ranges are available for correct hyphenation.

Warnings

breaking The helper function `to_utf8tex` was dropped in version 3.10.14. Code relying on this function will break upon upgrade.
Fix: Remove or replace calls to `to_utf8tex`. Review release notes for alternative functionality if needed, though this function was internal/helper-level.
gotcha The quality and availability of metadata vary significantly between services (Google Books, Open Library, Wikipedia, etc.). Some ISBNs may return incomplete or no data from a default service.
Fix: Explicitly try different services when fetching metadata, e.g., `meta(isbn, service='openl')` or `meta(isbn, service='wiki')`.
gotcha `isbnlib` distinguishes between a *structurally valid* ISBN (e.g., `is_isbn13()`) and an *issued* (registered) ISBN. An ISBN can be structurally correct but not yet assigned or found in metadata services.
Fix: Understand that `is_isbn13()` returning `True` does not guarantee an ISBN has been issued or that `meta()` will find data. Always handle cases where `meta()` returns an empty dictionary.
gotcha System package manager versions of `isbnlib` (e.g., via `apt` or `yum`) are frequently outdated and may not work correctly or contain the latest ISBN data ranges. `pip` is the recommended installation method.
Fix: Always install `isbnlib` using `pip` (`pip install isbnlib`) within a virtual environment. Avoid system-level package managers for Python libraries unless strictly necessary.
gotcha Configuration changes, such as setting default metadata services or API keys via `isbnlib.config` or `isbnlib.registry`, are session-specific and must be re-applied each time your application starts.
Fix: Place configuration calls (e.g., `config.add_apikey()`, `registry.setdefaultservice()`) at the entry point of your application or whenever a new session starts.

Install

pip install isbnlib Install stable version

Imports

canonical
wrong:
```
import isbnlib; isbnlib.canonical()
```
correct:
```
from isbnlib import canonical
```
Importing specific functions directly is idiomatic and clearer than importing the entire library and prefixing all calls.
is_isbn13
wrong:
```
import isbnlib; isbnlib.is_isbn13()
```
correct:
```
from isbnlib import is_isbn13
```
Importing specific functions directly is idiomatic and clearer.
meta
wrong:
```
import isbnlib; isbnlib.meta()
```
correct:
```
from isbnlib import meta
```
Importing specific functions directly is idiomatic and clearer, especially for frequently used functions like `meta`.
mask
```
from isbnlib import mask
```
info
```
from isbnlib import info
```

Quickstart

This quickstart demonstrates how to clean (canonicalize), validate, retrieve metadata, and hyphenate an ISBN using `isbnlib`'s core functions. It uses a known ISBN-13 and prints the results.

from isbnlib import canonical, is_isbn13, meta, mask

# An example ISBN-13 (striped, only digits and X)
isbn_like = "978-0446310789"

# 1. Canonicalize the ISBN
canonical_isbn = canonical(isbn_like)
print(f"Canonical ISBN: {canonical_isbn}")

# 2. Validate the ISBN
if is_isbn13(canonical_isbn):
    print(f"'{canonical_isbn}' is a valid ISBN-13 format.")
else:
    print(f"'{canonical_isbn}' is not a valid ISBN-13 format.")

# 3. Get metadata (default service is 'goob' - Google Books)
try:
    book_metadata = meta(canonical_isbn)
    if book_metadata:
        print("\nBook Metadata:")
        for key, value in book_metadata.items():
            print(f"  {key}: {value}")
    else:
        print(f"\nNo metadata found for ISBN: {canonical_isbn}")
except Exception as e:
    print(f"\nError fetching metadata: {e}")

# 4. Mask (hyphenate) the ISBN
hyphenated_isbn = mask(canonical_isbn)
print(f"\nHyphenated ISBN: {hyphenated_isbn}")

view raw JSON →