ATmega328P/Libraries/14. Install a ZIP, or by hand
Libraries · 14 of 33

Install a ZIP, or by hand

A library the Library Manager does not list comes as a ZIP, usually from GitHub. Sketch > Include Library > Add .ZIP Library unpacks it into the right place. Copying it in by hand works too, if the folder you copy is the library itself and not a folder that contains it.

Your board

When the Library Manager does not have it

Most libraries are in the Library Manager, and that is the place to install from: it picks the folder name, checks the version and offers updates. Some are not: a library a seller links from a product page, a fork with a fix that has not been released, or a newer version that only exists on GitHub so far.

Bounce2 shows the last case. The Library Manager installs release 2.71.0. On GitHub, the Code > Download ZIP button on the project page downloads the master branch instead, as Bounce2-master.zip, and its library.properties already says 2.72, a version that has not been released. The releases page offers Bounce2-2.71.zip, the same code the Library Manager has.

Either ZIP unpacks to one folder:

Bounce2-master/
  library.properties
  keywords.txt
  src/
    Bounce2.h
    Bounce2.cpp
  examples/
    bounce_basic/
    ...

That shape, library.properties and src/ at the top of one folder, is what the IDE looks for. An older layout with the .h and .cpp files directly at the top of the folder and no src/ also works.

Add .ZIP Library

Do not unzip it. In the IDE, choose Sketch > Include Library > Add .ZIP Library…, pick the ZIP, and the IDE:

  1. unpacks it into a temporary folder and checks there is exactly one folder at the top, with a header in it or in its src/;
  2. reads the library's name from library.properties, and
  3. copies the folder into your sketchbook's libraries, named after the library.

So Bounce2-master.zip lands as libraries/Bounce2, the same folder the Library Manager would have made. If that folder is already there, the IDE asks whether to overwrite it. A ZIP that is not one library in that shape is refused, and nothing is copied.

Or by hand

Unzipping it yourself and copying the folder into libraries works too, and it is the only route when a ZIP holds several libraries or arrives in a shape the IDE refuses. Restart the IDE after copying, so it rescans the folder.

What the libraries folder must look like
the IDE finds it
How it got there
Library folder
Bounce2
Header at the top or in src/
yes
Compiles
yes
Add .ZIP Library does the unpacking for you. It checks the archive holds one library, then names the folder after the library itself, so a ZIP called Bounce2-master.zip still lands as libraries/Bounce2.

The rule is the same as the one Add .ZIP Library checks: one folder per library, directly in libraries, with the header at its top or in its src/. The two shapes that break it are the two the figure shows in red. The nested one is easy to make by accident: Windows' Extract All, for one, suggests a new folder named after the ZIP and unpacks the ZIP's own folder inside it, so Bounce2-master/Bounce2-master/src/Bounce2.h is what you get. Copy that and the IDE finds no header one level down, and the compile ends with Bounce2.h: No such file or directory.

A hand-copied folder keeps the name you gave it. Bounce2-master compiles, but rename it Bounce2 anyway: with the plain name, installing from the Library Manager later replaces this folder instead of putting a second copy beside it, and a second copy is the subject of the next article.

Where to put it, by computer

ComputerThe sketchbook's libraries folder
WindowsDocuments\Arduino\libraries
macOSDocuments/Arduino/libraries
Linux~/Arduino/libraries

Those are the defaults. If you moved the sketchbook, File > Preferences > Sketchbook location names the folder; libraries is inside it. If there is no libraries folder there yet, make one.

When it does not work

Add .ZIP Library says the archive or library is not valid

The IDE wants exactly one folder at the top of the ZIP, with library.properties and a src folder, or the .h files, directly inside it. A ZIP with two folders at the top, or with the library one folder deeper, is refused. Unzip it, find the folder that holds library.properties, and copy that one by hand.

It asks whether to overwrite an existing library

A library of the same name is already installed, probably from the Library Manager. Overwrite replaces that folder with the ZIP's contents. Say yes only if you meant to swap versions; No leaves the installed one as it was.

The folder is in libraries and the header is still not found

Open the folder. If the first thing inside is another folder with the same name, it is nested: move the inner folder up into libraries and delete the empty outer one. If the .h and .cpp files sit loose in libraries, make a folder for them.

My hand-copied library does not show in File > Examples

Close the IDE and open it again after copying a library in by hand, so it rescans the libraries folder. If it still does not appear, the folder is not in the sketchbook the IDE is using: File > Preferences shows which one that is.

Where this goes next

Two copies of one library, which one the IDE compiled, and how to choose.

Versions, and "multiple libraries found" →

Edit this page — content/books/atmega328p/install-a-zip.mdx

Discuss this article

Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.

Browse Modules and blocks on the forum →