PlatformIO looks for your Arduino project in a specific folder, and you tell it where by setting the import path before you start

When you open PlatformIO and choose to import an Arduino project, the software needs to know which folder on your computer holds your code. You set this path — the location on your hard drive — before the import begins. PlatformIO will then read the files from that folder and set up the project structure it needs to compile and upload your code to the board.

The import path is not the same as where PlatformIO itself lives. It is the folder that contains your .ino files (your Arduino sketches) and any other project files you want to bring in. If you point PlatformIO to the wrong folder, it will not find your code, and the import will fail or import an empty project.

Key Takeaways

  • The import path is the folder on your computer that holds your Arduino sketch files, not the folder where PlatformIO is installed.
  • You set the import path in the PlatformIO import dialog before the import runs, usually by clicking a folder icon or typing the path directly.
  • If your Arduino project is in a subfolder (like Documents/MyArduinoProjects/Blink), you must point to that exact subfolder, not the parent folder.
  • PlatformIO will read your .ino files and any libraries or configuration files in that folder and recreate the project structure in its own format.

How to find and set your Arduino project folder

Start by locating the folder on your computer that holds your Arduino code. On Windows, this is often in Documents or a custom folder you created. On Mac or Linux, it might be in your home directory or a projects folder. The folder name usually matches your sketch name — for example, a sketch called "Blink" would be in a folder called Blink.

Open the folder and confirm it contains at least one .ino file. If you see only a folder with the same name inside (for example, Blink/Blink/), you may need to go one level deeper. Once you have found the right folder, note its full path. On Windows, you can right-click the folder, select Properties, and copy the location. On Mac, right-click and select "Copy as Pathname". On Linux, open a terminal in the folder and type pwd to see the full path.

Setting the path in PlatformIO's import dialog

In PlatformIO, go to File > Open Folder (or the equivalent in your version) and select Import Arduino Project. A dialog box will appear asking for the project location. You will see either a text field where you can paste the path, or a folder icon you can click to browse.

If you are pasting the path, make sure you copy the entire path from the folder properties or terminal, including the drive letter on Windows (C:\Users\YourName\Documents\Blink) or the full path on Mac (/Users/YourName/Documents/Blink). If you are using the folder browser, navigate to the folder that contains your .ino files and select it. Do not select a parent folder or a subfolder — select the exact folder where your sketches live.

What happens after you set the import path

Once you confirm the path, PlatformIO scans the folder for Arduino files and creates a new project structure. It reads your .ino files, detects the board type if it can, and sets up the folders it needs (src, include, lib, and others). This process usually takes a few seconds.

If PlatformIO cannot find any .ino files in the folder you selected, it will either show an error or create an empty project. If this happens, go back and check that you selected the correct folder. If the folder is correct but PlatformIO still does not see the files, the files may be named with a different extension or may be in a subfolder you missed.

Common mistakes when setting the import path

The most common error is selecting the parent folder instead of the project folder itself. If your code is in Documents/MyProjects/Blink, you must select the Blink folder, not MyProjects. PlatformIO will not search subfolders automatically.

Another mistake is pointing to the Arduino IDE's installation folder or sketch library folder instead of your own project. These are system folders that hold Arduino's own code, not your sketches. Your project folder is wherever you saved your .ino file when you created it in the Arduino IDE.

A third issue is using a path with special characters or spaces that your operating system does not handle well. If your folder is named "My Arduino Project" (with spaces), the path should still work, but if you are typing it manually, make sure the spaces are included exactly as they appear in the folder name.

If your project folder has moved or you need to change the path later

Once PlatformIO has imported your project, the import path is set and the project files are copied into PlatformIO's workspace. If you move your original Arduino folder, PlatformIO will not automatically find it — the imported project in PlatformIO is now independent.

If you want to import the same project again from a new location, you can create a new import and point to the new folder path. You can also manually edit the platformio.ini file in your PlatformIO project to change settings, but the import path itself is not something you change after import — it is only used during the import process.

Understanding the difference between import path and project location

The import path is where your Arduino code lives before you bring it into PlatformIO. The project location is where PlatformIO stores the imported project after the import is done. These are two different places on your computer.

When you import, PlatformIO reads from the import path and writes to the project location. If you delete the original Arduino folder after importing, your PlatformIO project will still work because PlatformIO has its own copy. However, if you want to keep both versions in sync, you will need to manage that yourself — PlatformIO does not automatically update the original folder when you edit the imported project.

Frequently Asked Questions

What if I do not know where my Arduino project folder is?

Open the Arduino IDE, go to File > Preferences (or Arduino > Preferences on Mac), and look at the "Sketchbook location" field. This is the folder where Arduino stores your sketches. Your project folder should be inside this location, named after your sketch. You can also search your computer for .ino files to find your project.

Can I import a project from a cloud folder like Google Drive or Dropbox?

Technically yes, but it is not recommended. If the cloud folder is not fully synced or the connection drops during import, PlatformIO may not read all the files correctly. It is safer to import from a folder on your local hard drive, then move the PlatformIO project to cloud storage if you want to back it up.

What if my project folder contains multiple .ino files?

PlatformIO will import all of them into the src folder. However, Arduino projects typically have only one main .ino file per folder. If you have multiple sketches you want to work on separately, create a separate folder for each one and import them as separate PlatformIO projects.

Do I need to set the import path every time I open PlatformIO?

No. The import path is only used during the import process itself. Once your project is imported, PlatformIO remembers the project and opens it automatically when you launch the software. You only set the import path when you are importing a new Arduino project for the first time.

What does PlatformIO do with my original Arduino folder after import?

PlatformIO leaves it alone. The import process reads your files but does not delete or modify the original folder. Your Arduino IDE can still access the original project. If you edit the code in PlatformIO, the original folder will not update automatically — you would need to manually copy changes back if you want both versions to match.