Skip to main content

Extract, clean, transform, hyphenate and metadata for ISBNs (International Standard Book Number).

Project description

Downloads Latest Version Download format Python Versions License Documentation Status Graph Coverage Built Status


If you are updating from 4.0.1 please:

Uninstall isbntools (sudo pip uninstall isbntools) and then delete all files isbntools* in your site-packages directory, including the folder isbntools

Then install isbntools 4.1.2 (sudo pip install isbntools).

NOTE: in Windows (or in OSX/Linux for an user install) you shouldn’t use sudo pip ..., just pip ...


isbntools provides several useful methods and functions to validate, clean, transform, hyphenate and get metadata for ISBN strings.

For the end user several scripts are provided to use from the command line:

$ to_isbn10 ISBN13

transforms an ISBN13 number to ISBN10.

$ to_isbn13 ISBN10

transforms an ISBN10 number to ISBN13.

$ isbn_info ISBN

gives you the group identifier of the ISBN.

$ isbn_mask ISBN

masks (hyphenate) an ISBN (split it by identifiers).

$ isbn_meta ISBN [wcat|goob|openl|isbndb|merge] [bibtex|msword|endnote|refworks|opf|json] [YOUR_APIKEY_TO_SERVICE]

gives you the main metadata associated with the ISBN, wcat uses (no key is needed), goob uses the Google Books service (no key is needed), isbndb uses the service (an api key is needed), openl uses the api (no key is needed), merge uses a merged record of wcat and goob records (no key is needed) and is the default option (you only have to enter, e.g. isbn_meta 9780321534965). You can get an API key for the service here. You can enter API keys and set preferences in the file isbntools.conf in your $HOME\.isbntools directory (UNIX). For Windows, you should look at %APPDATA%/isbntools/isbntools.conf. The output can be formatted as bibtex, msword, endnote, refworks, opf or json (BibJSON) bibliographic formats.

$ isbn_editions ISBN

gives the collection of ISBNs that represent a given book (uses

$ isbn_validate ISBN

validates ISBN10 and ISBN13.

$ ... | isbn_stdin_validate

to use with posix pipes (e.g. cat FILE_WITH_ISBNs | isbn_stdin_validate).

TIP Suppose you want to extract the ISBN of a pdf eboook (MYEBOOK.pdf). Install pdfminer and then enter in a command line:

$ -m 5 MYEBOOK.pdf | isbn_stdin_validate
$ isbn_from_words "words from title and author name"

a fuzzy script that returns the most probable ISBN from a set of words! (You can verify the result with isbn_meta)!

$ isbn_goom "words from title and author name" [bibtex|msword|endnote|refworks|json]

a script that returns from Google Books multiple references.

$ isbn_doi ISBN

returns the doi’s ISBN-A code of a given ISBN.

$ isbn_EAN13 ISBN

returns the EAN13 code of a given ISBN.

$ isbn_ren FILENAME

renames (using metadata) files in the current directory that have ISBNs in their filename (e.g. isbn_ren 1783559284_book.epub, isbn_ren "*.pdf").

Enter isbn_ren to see many other options.
$ isbntools

writes version and copyright notice and checks if there are updates.


$ isbn_repl

you will get a REPL with history, autocompletion, fuzzy options, redirection and access to the shell.

Following is a typical session:

$ isbn_repl

    Welcome to the isbntools 4.1.2 REPL.
    ** For help type 'help' or '?'
    ** To exit type 'exit' :)
    ** To run a shell command, type '!<shellcmnd>'

$ isbn> ?

Commands available (type ?<command> to get help):
BIBFORMATS  PROVIDERS  doi       exit        help  meta       to_isbn13
EAN13       audit      doitotex  from_words  info  shell      validate
EOF         conf       editions  goom        mask  to_isbn10

$ isbn> meta 9780156001311 tex
     title = {The Name Of The Rose},
    author = {Umberto Eco},
      isbn = {9780156001311},
      year = {1994},
 publisher = {Harcourt Brace}
$ isbn> meta 9780156001311 tex >>myreferences.bib
$ isbn> !ls
$ isbn> exit

Within REPL many of the operations are faster.

Many more scripts could be written with the isbntools and isbnlib library, using the methods for extraction, cleaning, validation and standardization of ISBNs.

Just for fun, suppose I want the most spoken about book with certain words in his title. For a quick-and-dirty solution, enter the following code in a file and save it as

#!/usr/bin/env python
import sys
from import *

query = sys.argv[1].replace(' ', '+')
isbn = isbn_from_words(query)

print("The ISBN of the most `spoken-about` book with this title is %s" % isbn)
print("... and the book is:")

Then in a command line (in the same directory):

$ python 'noise'

In my case I get:

The ISBN of the most `spoken-about` book with this title is 9780143105985

... and the book is:

{'Publisher': u'Penguin Books', 'Language': u'eng', 'Title': u'White noise',
'Year': u'2009', 'ISBN-13': u'9780143105985', 'Authors': u'Don DeLillo ;
introduction by Richard Powers.'}

Have fun!


From the command line enter (in some cases you have to precede the command with sudo):

$ pip install isbntools


$ easy_install isbntools


$ pip install isbntools-4.1.2.tar.gz

(first you have to download the file!)

You should check if the install was successful, by enter:

$ isbntools

Portable Version (Windows and Linux)

If you are on a Windows or Linux system, you can download a portable version that doesn’t need python and gives you access to the scripts. However, doesn’t support add-ins or customization!


  1. unzip the file and put the file isbn.exe in a folder.
  2. go to that folder and open a command line.
  3. run isbn help to get further instructions.

For Devs

If all you want is to add isbntools to the requirements of your project, probably you will better served with isbnlib, it implements the basic functionality of isbntools without end user scripts and configuration files!

If you thing that that is not enough, please read at least this page of the documentation.

If you would like to contribute to the project please read the guidelines.

Conf File

You can enter API keys and set preferences in the file isbntools.conf in your $HOME/.isbntools directory (UNIX). For Windows, you should look at %APPDATA%/isbntools/isbntools.conf (create these, directory and file, if don’t exist [Now just enter isbn_conf make!]). The file should look like:







The values are self-explanatory!

NOTE If you are running isbntools inside a virtual environment, the isbntools.conf file will be at the root of the environment.

The easier way to manipulate these files is by using the script isbn_conf. At a terminal enter:

$ isbn_conf show

to see the current conf file.

This script has many options that allow a controlled editing of the conf file. Just enter isbn_conf for help.


To get extra functionality, search pypi for packages starting with isbntools.contrib or type at a terminal:

$ pip search isbntools

for a nice formated report!

Known Issues

  1. The meta method and the isbn_meta script sometimes give a wrong result (this is due to errors on the chosen service), in alternative you could try one of the others services.
  2. The isbntools works internally with unicode, however this doesn’t solve errors of lost information due to bad encode/decode at the origin!
  3. Periodically, agencies, issue new blocks of ISBNs. The range of these blocks is on a database that mask uses. So it could happen, if you have a version of isbntools that is too old, mask doesn’t work for valid (recent) issued ISBNs. The solution? Update isbntools often!
  4. Calls to metadata services are cached by default. If you don’t want this feature, just enter isbn_conf setopt cache no. If by any reason you need to clear the cache, just enter isbn_conf delcache.

Any issue that you would like to report, (if you are a developer) please do it at github or at stackoverflow with tag isbntools, (if you are an end user) at twitter.

More documentation at Read the Docs.

Project details

Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
isbntools-4.1.2.tar.gz (32.1 kB) Copy SHA256 hash SHA256 Source None Feb 11, 2015

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page