Including an external file in Arduino code

Hi. I'd like to be able to include external files in my Arduino code. Here's an example that works as intended:

Arduino code, saved as: 'C:\Arduino\IncludeTest\IncludeTest.ino': (note 'led' is not defined locally; the program will fail without its include file)

#include "C:\Arduino\IncludeTest\Includes\Include.h"

void setup() {                
  pinMode(led, OUTPUT);     

void loop() {
  digitalWrite(led, HIGH);
  digitalWrite(led, LOW);

Include file, saved as: 'C:\Arduino\IncludeTest\Includes\Include.h': (note 'unsigned char' used rather than 'byte' because '.h' file is interpreted as c, not as Arduino code)

const unsigned char led = 13;

This program works. The only issue is that the entire path of the include file needs to be present in the #include command. Consequently, moving the Arduino program to a new folder will break the link, and it will not compile until you correct the #include path.

Is there a way to include a file using a relative link rather than an absolute one? For example:

include ".\Includes\Include.h"

I know the most obvious answer is to place the include file in the same folder as the main '.ino' file, so it will automatically be included. This won't help me, because all the program files located in this folder are also loaded in the IDE, and saved over when the IDE saves. I want the include file to remain independent of the Arduino IDE, and not be modified by it.

I've seen similar questions asked on a couple of threads, but I've never seen a satisfactory answer to it. Can anyone help?

If the file .h is saved "as library" you can include only the name and IDE copy the code in temporary directory when compile your sketch. A library can be only a .h file

You can also split your code of a single sketch using tabs of IDE. But all the files will be in the same directory and for the same sketch (no reusing code of .h as library)

For portability, I'd like my include files to be located in the same directory as the main program '.ino' files, or in a subdirectory of it.

I don't think this is possible with libraries, since they are located somewhere under the main Arduino IDE folder. Is this correct? Also, the include files will be unique to the program they are associated with, so using a library for each one doesn't seem appropriate in this case.

paulrd: I don't think this is possible with libraries, since they are located somewhere under the main Arduino IDE folder. Is this correct?

A library is for using with many sketchs.

So, you need only to split code in many files. Use tabs method. See IDE page on Arduino site.

Tabs aren't appropriate either, because I don't want the include files to be overwritten when saving from the IDE.

Have you tried using relative path?
Your sample:

#include ".\Includes\Include.h"

I think IDE can understand this command.

Yes. It would be wonderful if that worked but it doesn't. That's why I'm here.

I think the compiler works in a different location so it gives a 'No such file or directory' error.

all the program files located in this folder are also loaded in the IDE, and saved over when the IDE saves.

I would only expect a source file to be overwritten if you had modified the content within the IDE and then saved that tab.

I want the include file to remain independent of the Arduino IDE, and not be modified by it.

The Arduino scheme for doing this is to put your common code in an Arduino library. Two library locations are supported. The library directory within the Arduino software installation directory is intended for libraries which are shipped as part of the IDE. The library directory within your documents directory (i.e. where your sketches are normally saved) is intended for libraries you have downloaded or created yourself. If you put your common code in a library in either of these locations then it will be included in the sketch but not opened and displayed in the IDE. That seems to be what you want to achieve.

Thanks Peter, I did some tests and you're right, the IDE doesn't save files unless they've been modified.

However, there's another reason why keeping the include files as tabs won't work for me - I want my include files to contain 'const' definitions, which will not work unless they are at the beginning of the main program '.ino' file. Can you think of any workaround for this?

Your suggestion to locate the include files as libraries in my documents folder is another option, but this means the program is no longer contained in a single folder, and I'd really like it to be self-contained and portable. The include files are only relevant to a single program, so aren't libraries in the usual sense.

Is anyone aware of a solution that exactly fits my original request? I hoped someone might be able to work some simple magic with C preprocessor commands or something similar.

I just tried to create a header file (header.h) and placed the following lines in it:

const int MYVAL = 10;
const float THISVAL = 5.0;

This header file is placed in the same directory as the INO sketch file, which holds:

#include "header.h"

extern const int MYVAL;
extern const float THISVAL;

void setup() 
  int i;
  for (i = 0; i < MYVAL; i++)

void loop()

This works just fine for me, but I’m not sure it solves your problem. For this to work, make sure both the header file and the sketch (.ino) file must be in the same directory.

Yes the #include command overcomes the problem with 'const' definitions - thanks. And it's almost a solution to my problem... But sadly I find the IDE compiles whatever is displayed in the IDE, regardless of changes to the underlying files. So if I modify my include files outside the IDE, the modified versions will be ignored.

So doing it this way doesn't allow modifiable include files that are truely independent of the IDE.

Have you considered using an external editor? If you do the Arduino IDE just compiles the latest version of the files and you can’t intentionally or accidentally change the files using the IDE.

I have run into the same problem as I wanted to have a different .ino file for slightly different projects, but all sharing common code. I eventually settled for a #include with a fully qualified path name in the .ino file. The relative #includes in the file that is included by the first #include work perfectly (hope that makes sense).

The alternative seems to be to use avrdude from the command line - life’s too short :slight_smile:


I'd consider using an external editor but ideally I'd like my methods to be compatible with the Arduino IDE as well. I think the simplest workaround for this is to use a full path name in #include statements, as you say.

If I can't find a solution I may suggest this as a potential area for improvement on the Arduino Development forum. I think all it would take is an environment variable containing the path to the original '.ino' files. Apparently I'm not the only one who would appreciate this, and it wouldn't change anything for anyone else.

My PC runs Ubuntu Linux and I use the Gedit editor for all my Arduino program creation and editing. I'm not sure what the equivalent Windows editor is - notepad, perhaps. Gedit does all the code highlighting and bracket matching stuff.

An external editor is completely compatible with the Arduino IDE. Obviously you need to follow the Arduino scheme of having the principal .ino file in a directory of the same name. The you just open the .ino file with the IDE (which won't let you edit the file if you have selected an external editor) and verify and upload as normal. When there is a mistake in the code I just correct it in Gedit, save the file and the IDE automatically knows it has changed and uses the new version.