Library in a private gitlab repository

Hi all,

I’m writing a private library for pio.
I want that library to be in a private repository in gitlab.
In my repo I have the following directory scheme:

|- repo/
    |- include/
        |-- hpp_files
    |- src/
        |-- cpp_files
    |-- to_exclude.txt
    |-- library.json

The library.json file is similar to the following:

    "name" : "my_lib",
    "description" : "my lib!",
    "keywords" : "word1, word2, word3",
    "repository" : {
        "type" : "git",
        "url" : ""
    "frameworks" : "mbed",
    "version" : "1.0.0",
    "export" : {
        "include" : [
       "exclude" : "to_exclude.txt"

If I install that library in a project with the command:
pio lib install git+
PlatformIO installs asks me the username and password of gitlab and installs the library but it ignores some keywords in the library.json file:

  • version is not 1.0.0 but is the hash of the last commit in the master branch of git.
  • export is ignored and all the files are downloaded in project/.piolibdeps/my_lib/ even to_exclude.txt.

Why is that happening?

I’m not sure exactly about the version field, but I think your export issue is related to the fact the library.json file is really only for the PlatformIO Library Registry Crawler… in order to populate information for the online library database. i.e.


Explain [to] PlatformIO Library Crawler which content from the repository/archive should be exported as “source code” of the library. This option is useful if need to exclude extra data (test code, docs, images, PDFs, etc). It allows one to reduce size of the final archive.

This is referring to the archive downloaded if you specify the library to be installed just by name or ID, which is also available from the bottom of the ‘Installation’ tab of any library listing. Since you’re installing the library from git… I believe almost no processing would happen… as it would do a git clone and basically nothing else. The version issue would also stem from this because it’s not being pulled from the library database. It may behave differently if you tag a commit with the same version number as you specified in the library.json, but that may also be specific functionality of the crawler…

Addendum: If you look at the version control in relation to the lib install command… it suggests that version control for a VCS lib install is done by tag name, branch or commit id… and there is no mention that a library.json will be parsed…

1 Like

All right,
I’ve done a lot of tests, What I’ve understood is that: the version of the library.json file is ignored because when you run commands like pio lib install git+https://link-to-repo/repo.git the link is used as “version”. This happens even in the dependencies field of the library.json file: if you want to depends on another private library you should write in your library.json something like:

"dependencies": [
        "name" : "otherLib",
        "version": "git+https://link-to-my-git-server/other-repo.git"

For the export keyword, It does not influence the number of file downloaded, but it can change the file that are compiled by the platformio build task.

1 Like