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.
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:
- 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/; - reads the library's name from
library.properties, and - 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.
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
| Computer | The sketchbook's libraries folder |
|---|---|
| Windows | Documents\Arduino\libraries |
| macOS | Documents/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
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.
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.
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.
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.
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.