Usage

This section details all the uses of browser-history with complete code examples for each. Refer the Quick Start for basic usage.

Using the API

browser-history has an API that allows you to extract history and bookmarks through python code, perhaps in other python programs.

History

The main use case of browser-history is to extract browsing history from various browsers installed on the system.

History from all browsers

To get consolidated history from all browsers:

from browser_history import get_history

outputs = get_history()

# his is a list of (datetime.datetime, url, title) tuples
his = outputs.histories

History from the default browser

Warning

Experimental feature. This only works on Linux and Windows, but not for every browser. (see this PR to check browser and platform support)

Let browser-history automatically detect the default browser set in the system:

from browser_history.utils import default_browser

BrowserClass = default_browser()

if BrowserClass is None:
    # default browser could not be identified
    print("could not get default browser!")
else:
    b = BrowserClass()
    # his is a list of (datetime.datetime, url, title) tuples
    his = b.fetch_history().histories

History from a specific browser

If you need histories from a specific browser:

from browser_history.browsers import Firefox

f = Firefox()
outputs = f.fetch_history()

# his is a list of (datetime.datetime, url, title) tuples
his = outputs.histories

Firefox in the above snippet can be replaced with any of the Supported Browsers.

History from a specific profile of a browser

browser-history can also extract history from one particular profile of a browser. The profile directory is usually quite different across different systems, this workflow is better suited for the command line tool.

Example:

from browser_history.browsers import Firefox

b = Firefox()

# this gives a list of all available profile names
profiles_available = b.profiles(b.history_file)

# use the history_profiles function to get histories
# it needs a list of profile names to use
outputs = b.history_profiles([profiles_available[0]])

his = outputs.histories

Save histories to a file

Use outputs.save("filename.ext") to save histories to a file (outputs is obtained from fetch_history as shown in the previous examples). ext should be one of the supported extensions (csv, json, jsonl, etc.). See save() for the list of all supported extensions.

Example:

from browser_history import get_history

outputs = get_history()

# save as CSV
outputs.save("history.csv")
# save as JSON
outputs.save("history.json")
# override format
outputs.save("history_file", output_format="json")

Bookmarks

Warning

Experimental feature. Although this has been confirmed to work on multiple (Firefox and Chromium based) browsers on all platforms, it is has not been tested as much as the history feature.

browser-history also supports extracting bookmarks from some browsers.

All of the usage is similar to extracting history (including saving to a file). You can use the same code examples from History with the following changes:

Replace fetch_history with fetch_bookmarks (and get_history with get_bookmarks)
Replace outputs.histories with outputs.bookmarks

Bookmarks (from outputs.bookmarks) are a list of (datetime.datetime, url, title, folder) tuples.

Using the CLI

browser-history provides a command-line interface that can be accessed by typing browser-history in a terminal (in Windows, this will be the CMD command prompt or powershell).

The CLI provides all of the functionality of browser-history (please open an issue if any feature is missing from the CLI).

More information about the CLI here: Command Line Interface.