How to add a library thats is not available in pio as 'standard' library

dbyy · March 12, 2026, 8:33pm

Hello,

I’m wondering, how can I add a library that is not available in pio to use it in a project?

I want to create a project that is using the library ILI9844 which is not part of pio, however I have the zip file for this library.

I would like to use this library for more then one projects down the road and want to avoid adding it to each project every time.

What would be the best way to add this library to my pio setup?

If possible please reference me to a good tutorial or documentation.

Thanks

maxgerhardt · March 12, 2026, 10:03pm

You can install your library globally:

Or simply unpack the library in C:\Users\<user>\.platformio\lib\<your library name here>.

However, for good reusability accross multiple computers, it is actually recommended you specify all libraries a project needs per-project in the platformio.ini via lib_deps.

You can also reference ZIP files

lib_deps =
   file://../my_global_libs/ILI9341.zip

Or even better: Upload the library somewhere (e.g., Github), and reference that.

lib_deps =
   https://githhub.com/myuser/myproject.git#some_version_tag

dbyy · March 13, 2026, 2:49pm

Hi Max,

That’s a very detailed and helpful information.

I will give it a shot.

Viele Grüẞe nach Bochum.

Thanks

dbyy · March 14, 2026, 1:59pm

Thanks again for the suggestions.

In the meantime I tested different scenarios with lib_deps entry in platformio.ini.

These are my results:

type: extracted “master” zip file
Platformio.ini: file:~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32
compile message: Library Manager: Installing file:~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32
VCSBaseException: VCS: Unknown repository type file:~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32 - no success
type: “master” zip file
Platformio.ini: file:/home/fred/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip
compile message: Library Manager: Installing file:/home/fred/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip
VCSBaseException: VCS: Unknown repository type file:/home/fred/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip - no success
type: “master’ zip file
Platformio.ini: file:$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip
compile message: Library Manager: Installing file:$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip
VCSBaseException: VCS: Unknown repository type file:$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip - no success

In addition, if I’m tried the version #2 and #3 the “extracted” archive version, it failed as well.

I’m wondering, is there something wrong in my syntax?

The only two versions that were successful was the use of the URL to the github library: https://github.com/dbyy/ILI9488-ESP32#master and the use of the custom library in the project folder structure itself (see attached screen shot)

I would prefer using a reference to a ’local’ library

Thank you for your time.

maxgerhardt · March 14, 2026, 2:32pm

You have to use file://. It’s a protocol. Like https://.

Similiarly symlink://<path> if you don’t want it to create a copy but just a symbolic link.

I.e. use

lib_deps =
   file://~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32

if you want it to copy the library from ~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32, or, without file duplication

lib_deps =
   symlink://~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32

Again, carefully inspect the documentation for allowable protocols to point to libraries.

maxgerhardt · March 14, 2026, 2:41pm

If you’re fine with using a deprecated option:

Just put

lib_extra_dirs =
    ~/Documents/PlatformIO/custom-libraries/

and libraries will be found automatically in there. No need to add each library individually.

dbyy · March 16, 2026, 12:07am

I continued the testing using a custom library.

Nothing has changed on the locations from my previous post /home/fred/Documents/PlatformIO/custom-libraries/ILI9488-ESP32

I tried the following variations in platformio.ini in lib_deps section:

file://~/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/
file://$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/
file://$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/ILI9488-ESP32-master.zip

In all cases I got a long list of error messages (with the only difference of the contents of “FileNotFoundError: [Errno 2] No such file or directory: ‘…….’).

error message #1
================
Library Manager: Installing file://$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/
FileNotFoundError: Traceback (most recent call last):
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/__main__.py", line 103, in main
    cli()  # pylint: disable=no-value-for-parameter
    ~~~^^
  File "/home/fredplatformio.ini/.platformio/penv/lib/python3.13/site-packages/click/core.py", line 1485, in __call__
    return self.main(*args, **kwargs)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/click/core.py", line 1406, in main
    rv = self.invoke(ctx)
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/cli.py", line 85, in invoke
    return super().invoke(ctx)
           ~~~~~~~~~~~~~~^^^^^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/click/core.py", line 1873, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/click/core.py", line 1269, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/click/core.py", line 824, in invoke
    return callback(*args, **kwargs)
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/click/decorators.py", line 34, in new_func
    return f(get_current_context(), *args, **kwargs)
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/run/cli.py", line 147, in cli
    process_env(
    ~~~~~~~~~~~^
        ctx,
        ^^^^
    ...<9 lines>...
        verbose,
        ^^^^^^^^
    )
    ^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/run/cli.py", line 210, in process_env
    ).process()
      ~~~~~~~^^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/run/processor.py", line 81, in process
    install_project_env_dependencies(
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        self.name,
        ^^^^^^^^^^
    ...<3 lines>...
        },
        ^^
    )
    ^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/package/commands/install.py", line 133, in install_project_env_dependencies
    _install_project_env_libraries(project_env, options),
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/package/commands/install.py", line 253, in _install_project_env_libraries
    env_lm.install(
    ~~~~~~~~~~~~~~^
        spec,
        ^^^^^
        skip_dependencies=options.get("skip_dependencies"),
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        force=options.get("force"),
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/package/manager/_install.py", line 47, in install
    pkg = self._install(spec, skip_dependencies=skip_dependencies, force=force)
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/package/manager/_install.py", line 97, in _install
    pkg = self.install_from_uri(spec.uri, spec)
  File "/home/fred/.platformio/penv/lib/python3.13/site-packages/platformio/package/manager/_install.py", line 187, in install_from_uri
    shutil.copytree(_uri, tmp_dir, symlinks=True)
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/fred/.local/share/uv/python/cpython-3.13.11-linux-x86_64-gnu/lib/python3.13/shutil.py", line 591, in copytree
    with os.scandir(src) as itr:
         ~~~~~~~~~~^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '$HOME/Documents/PlatformIO/custom-libraries/ILI9488-ESP32/'

============================================================

An unexpected error occurred. Further steps:

* Verify that you have the latest version of PlatformIO using
  `python -m pip install -U platformio` command

* Try to find answer in FAQ Troubleshooting section
  https://docs.platformio.org/page/faq/index.html

* Report this problem to the developers
  https://github.com/platformio/platformio-core/issues

============================================================

I have to stress, this is the same library as when retrieved (successfully) from github, without any error messages.

And to learn more about the ‘protocols’ that can be used in platformio.ini, I searched the whole documentation side but was not able to locate an entry that is explaining the use of file:// and symlink://

Thanks for your attention.