Last updated May 20, 2015. Created on November 15, 2011.
Edited by BeatnikDude, therobyouknow, glass.dimly, drupalshrek. Log in to edit this page.

See also: The ideas and design behind Libraries API 2.x


Libraries API 2.x includes a library registry, so if you want to use an external library in your module, you need to make it known first. You can do this by implementing either hook_libraries_info() in your module or by providing an info file for your library, which users then have to download.

Using hook_libraries_info()

 * Implements hook_libraries_info().
 * For defining external libraries.

function simple_libraries_info() {

  // A very simple library. No changing APIs (hence, no versions), no variants.
  // Expected to be extracted into 'sites/all/libraries/simple'.
  $libraries['simple'] = array(
    'name' => 'Simple library',
    'vendor url' => '',
    'download url' => '',
    'version arguments' => array(
      'file' => 'simple.js', // Could be any file with version info
      'pattern' => '/Version (\d+)/',
      'lines' => 5,
    'files' => array(
      'js' => array('simple.js'), //this can be a path to the file location like array('lib/simple.js')

  return $libraries;

Version detection

Version detection is using regular expressions. If you'd like to bypass the version detection regex you can replace the "version arguments" array with a callback as demonstrated below:

  $libraries['simple'] = array(
    'name' => 'Simple library',
    'vendor url' => '',
    'download url' => '',
    'version callback' => 'simple_version_callback',
    'files' => array(
      'js' => array('simple.js'), //this can be a path to the file location like array('lib/simple.js')

function simple_version_callback() {
  //use some fancy magic to get the version number... or don't
  return TRUE;

Using an .info file

The info file should be in the same format as a regular Drupal info file for a module or theme, and should contain exactly the same keys that are described in hook_libraries_info().

name = CustomLibrary
machine name = CustomLibrary
description = Provides an interface to the CustomLibrary
version = 1
files[php][] =

Required information are name, machine name, version and files. This info file must be placed in the top level library directory, e.g. sites/all/libraries. In this example the file will need to be in sites/all/libraries/CustomLibrary/. The info file must be entirely lowercased, otherwise it will not be found.

The info file must be named $ (where $name is the machine name of the library) and placed in the top level of one of the libraries directories (e.g. sites/all/libraries).

When choosing the internal name ("machine name", will be $name below) of your library, please check for other libraries or Drupal modules with the same name first.

If you have Drush installed, you can see whether Libraries API found your library information by running drush libraries-list in the context of your Drupal site. Otherwise, you can check the output of libraries_info($name).

If Libraries API has found your library, you're ready to use the library in your module!


To load the library from inside your module, simply do:


Usually, you'll want to do something after the library has been loaded. Because you cannot always depend on the library being installed you have to check first if the loading was actually successful:
// Try to load the library and check if that worked.
if (($library = libraries_load($name)) && !empty($library['loaded'])) {
  // Do something with the library here.


If you just want to check whether the library is installed, but don't want to load it right away, you can use:

$library = libraries_detect($name);

Similar to checking whether the library was loaded above, we can then check if the library is installed:
if (($library = libraries_detect($name)) && !empty($library['installed'])) {
  // The library is installed. Awesome!
else {
  // Something went wrong. :(
  // This contains a short status code of what went wrong, such as 'not found'.
  $error = $library['error'];
  // This contains a detailed (localized) error message.
  $error_message = $library['error message'];

You can also attach library to renderable array like that

$form['myelement']['#attached']['libraries_load'][] = array('myAwesomeLibrary');

Looking for support? Visit the forums, or join #drupal-support in IRC.


jnicola’s picture

Just wanted to throw it out there... that this is confusing and in trying to work with this libraries module, it's turned a very very stupid simple module into a headache to configure, and not nearly as simple to hand off.

How the heck do you write a .info file for a JS library.

TwoD’s picture

EDIT: removed a more lengthy response since it's already answered better on the other pages related to this module.

In short; You don't have to write a .info file for a library if you don't want to. Just implement hook_libraries_info() in a small Drupal module by following the examples in libraries.api.php. That way is currently better documented. Need help with the rest, file a support request in the issue queue and ask them to update the docs as well.

munroe_richard’s picture

While it's possible to specify different versions and variants of those versions of external libraries, damned if I can figure out how you actually load a SPECIFIC version of a libary (and, of course, variant within that version).

So, how is that done?

And how in the world do you use the callbacks?

I've spent a few days pouring over the libraries code itself trying to figure this out with no joy.

Any help would be appreciated.


Dick Munroe

weboide’s picture

You could use libraries_detect() to check the current installed version and see if there's the variant and version you need.

jvdurme’s picture

Actually, the bundles libraries.api.php file says that only one version can be installed and used per site, since it will always get the same library name.
You can only detect the version that is installed so your module can cope with that version.
So I don't think you can load specific versions, you can only detect the version, then use the version info to adapt your module.

Found this in libraries.api.php of the libraries package line 31.


TechNikh’s picture

I found the test module very useful for different version code.

$libraries['example_supported_version'] = array(
    'name' => 'Example supported version',
    'library path' => drupal_get_path('module', 'libraries') . '/tests/libraries/example',
    'version callback' => '_libraries_test_module_return_version',
    'version arguments' => array('1'),
    'versions' => array(
      '1' => array(),


In 30 seconds set up Automated Visual testing of your website. Zero coding.
Ever dreamed of styling your view, We have a solution for you.

weboide’s picture

Since the libraries info data is cached, remember to clear the cache everytime you change your hook_libraries_info() data. That'll save you some headaches.

CChow’s picture

The latest google-api-php-client has the following file structure:
... and so on.

Its files use require_once with paths such as "Google/Auth/AssertionCredentials.php"

These paths can't be found, since php doesn't look for them in /sites/all/libraries/google-api-php-client/src

The libraries module cannot help here. Instead, you have to manually set the include path before you load the library, as such
edit: nevermind, I can't get the libraries module to detect google-api-php-client v. 1.0.5-beta

augbog’s picture

Something I've realized is you can't simply copy and paste google-api-php-client... If you have drupal running on the server, try downloading the zip master file from github, moving that to the libraries directory and directly unzipping it there and changing the name from google-api-php-client-master to google-api-php-client.

After you do that, clear your cache and it should hopefully work. I don't know what the difference is but this worked for me

augustofagioli’s picture

yes! clean cache and save headache

tlabarge’s picture

The Loading and Detection sections above show examples where library loading/detection is done within the PHP global scope, just after the opening php tag. However, from looking at the way other Drupal modules are structured, I usually do not see much code other than define statements within the global scope.

Should libraries be loaded from the global scope as shown above, or are there better places to do that (inside of a hook for example?) I'm new to using the Libraries API, so I'm wondering what the best practices are here.