Arduino needs to know the folder path where your library code lives

When you write code in the Arduino IDE and want to use a library — a pre-written chunk of code that handles a specific task — the IDE has to find that library's files on your computer. By default, Arduino looks in a standard folder called the libraries folder. If your library is somewhere else, or if you want to organize multiple versions of the same library, you tell Arduino the exact path to that folder using the IDE's settings.

The most direct way is through the Arduino IDE's preferences menu, where you can add custom library paths. You can also place libraries in the standard location and let Arduino find them automatically. The method you choose depends on whether you want one library available to all your projects, or whether you need different versions for different sketches.

Key Takeaways

  • The Arduino IDE looks for libraries in a default folder — usually called libraries inside your Arduino sketchbook folder — unless you tell it to look elsewhere.
  • You can add extra library search paths through File > Preferences > Sketchbook location, then manually creating a libraries folder there.
  • The IDE also reads libraries from a system-wide location: Arduino/libraries in your Documents folder on Windows, or ~/Documents/Arduino/libraries on Mac and Linux.
  • If you place a library in the correct folder with the right structure — a folder containing a .cpp file, a .h file, and a keywords.txt file — Arduino will find it automatically on restart.
  • You can also import a library from a ZIP file through Sketch > Include Library > Add .ZIP Library, which handles the path setup for you.

The default libraries folder and where Arduino looks first

When you install the Arduino IDE, it creates a folder structure on your computer. Inside that structure is a libraries folder. This is the first place the IDE looks when you try to use a library in your code. On Windows, this folder is usually at Documents\Arduino\libraries. On Mac, it is ~/Documents/Arduino/libraries. On Linux, it is ~/Arduino/libraries.

If you put a library folder directly into this location, the IDE will find it without any extra steps. The library folder must contain at least three files: a .cpp file (the actual code), a .h file (the header that tells the IDE what functions are available), and a keywords.txt file (which tells the IDE how to color-code your library's functions in the editor). The folder name itself becomes the library name you use in your code.

You can see where your sketchbook folder is by opening the IDE, going to File > Preferences, and looking at the "Sketchbook location" field. The libraries folder sits inside that location. If no libraries folder exists yet, you can create one manually.

Adding a custom library path through preferences

If you want the IDE to search in a different location — perhaps a folder on an external drive, or a shared network folder — you can add that path through the preferences. Open the Arduino IDE, click File > Preferences (on Mac, Arduino > Preferences). Look for the field labeled "Sketchbook location." This shows where your main Arduino folder is.

Create a libraries folder inside your sketchbook location if one does not already exist. The IDE will automatically search this folder when you restart. If you want to add a path outside your sketchbook folder, there is no direct preference field for it in the standard IDE. Instead, you can use the command line or manually edit the preferences.txt file, but this is rarely necessary — most users keep libraries in the default location.

A simpler approach: if you have libraries in multiple places, move them all into the standard Documents/Arduino/libraries folder. This keeps your setup straightforward and avoids confusion when you switch computers or update the IDE.

Importing a library from a ZIP file

Many libraries are distributed as ZIP files, especially those you read from GitHub or a library author's website. Instead of manually extracting and placing the folder, you can use the IDE's built-in import tool. Open the IDE, go to Sketch > Include Library > Add .ZIP Library. A file browser opens. Navigate to your ZIP file and select it.

The IDE extracts the ZIP, places the library in the correct location, and restarts the library index automatically. This method handles the path setup for you and is the safest way to install a library if you are unsure about folder structure. After import, the library appears in your Sketch > Include Library menu and is ready to use.

How the IDE finds and loads a library when you use it in code

When you write #include <MyLibrary.h> in your sketch, the IDE searches for a folder named MyLibrary in all the library paths it knows about. It looks first in the default libraries folder, then in any custom paths you have added. Inside that folder, it finds the .h file and reads the function definitions.

When you compile your sketch, the IDE also finds the .cpp file in the same folder and compiles that code together with your sketch. If the IDE cannot find the library folder, you will see an error like "fatal error: MyLibrary.h: No such file or directory." This means the folder name does not match what you typed in the #include statement, or the folder is not in any of the search paths.

The IDE caches the list of available libraries when it starts. If you add a new library folder while the IDE is open, you need to restart the IDE for it to recognize the new library. This is why many tutorials tell you to restart after installing a library.

Organizing multiple versions of the same library

Sometimes you need different versions of a library for different projects — perhaps an older version works with one device, and a newer version works with another. The IDE loads only one version at a time, so you cannot have two folders with the same name in the same search path.

One solution is to rename the folders: MyLibrary_v1 and MyLibrary_v2. Then in your sketch, use #include <MyLibrary_v1.h> to specify which version you want. Another approach is to keep one version in the default libraries folder and store alternate versions in a separate folder, then manually copy the version you need before you compile.

A cleaner method is to use a version control system like Git to manage different versions in different branches, but this requires familiarity with Git and is more common in professional development than in hobby Arduino projects.

Troubleshooting when Arduino cannot find your library

If the IDE says it cannot find your library, check these things in order. First, verify the folder name matches exactly what you typed in the #include statement — folder names are case-sensitive on Mac and Linux, and the IDE is strict about matching. Second, confirm the folder is in one of the search paths: the default libraries folder, or inside your sketchbook folder. Third, make sure the folder contains a .h file with the same name as the folder.

If you moved or added a library while the IDE was open, restart the IDE. If you edited the preferences.txt file by hand, check for typos in the path — a single wrong character will cause the path to be ignored. On Windows, use backslashes in paths; on Mac and Linux, use forward slashes. If you are still stuck, delete the library and reinstall it using the ZIP import method, which handles all the path logic for you.

Frequently Asked Questions

Can I put a library anywhere on my computer?

Not without extra setup. The IDE searches only in the default libraries folder and any paths you add through preferences. For most users, placing the library in Documents/Arduino/libraries is the simplest approach. If you need a library in a custom location, you can edit the preferences.txt file directly, but this is error-prone and rarely necessary.

What if two libraries have the same name?

The IDE loads the first one it finds in its search order. If you have duplicates, rename one of them to something unique, then update your #include statement to match. This prevents confusion and ensures you are using the version you intended.

Do I need to restart the IDE after adding a library?

Yes. The IDE builds its library index when it starts. If you add a library folder while the IDE is running, it will not see it until you restart. This applies whether you manually copy a folder or use the ZIP import tool.

Can I use a library from a network drive or external USB drive?

Yes, but the path must be consistent. If you use an external drive, the drive letter or mount point might change between computers or sessions, breaking the path. For portable setups, keep libraries on the same drive as your sketches, or use the ZIP import method to copy them into the standard location.

What does the keywords.txt file do?

It tells the IDE how to color-code your library's functions in the editor. It is not required for the library to work, but it makes your code easier to read. The file lists function names and constants, one per line, with a tab character separating the name from its color category.