How to make your own Gentoo Linux overlay

So before we start, I have my own overlay @ and am running it for a while, it was a bit painful for me to make one at the start and to help new Gentoo users I am making this blog post, anyway, here's how you do it:

Step one -- Think of a name

Think of a name you will give your overlay because this information will be needed in later steps

Step two -- Folder structure

To start with we need files and folders to work with, all names ending with a / are folders and everything else is a file, please make sure to also apply the templates in <...>, for example <year> would be the current year:

├── metadata/
│  └── layout.conf
├── overlays.xml
├── profiles/
│  └── repo_name
├── repositories.xml
├── sets/
├── sets.conf
└── <overlay name>.conf

Step three -- License

The LICENSE file should have your license, if it doesn't already please pick one, for example on my overlay I went for GPLv3, but you can also go for some other open source licenses, like GPLv2, WTFPL, BSD 3-clause, etc.

Write that license to the LICENSE file

Step four -- Master overlays

This step is always the same, you have to set the master overlay in metadata/layout.conf file, the master is usually going to be gentoo, so in metadata/layout.conf add this content:

masters = gentoo

Step five -- Overlay index files

Overlay index files are these files:

Both of these files should have the same content, make sure to fill in the templates that are in SCREAMING_SNAKE_CASE:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "">
<repositories xmlns="" version="1.0">
    <repo quality="experimental" status="unofficial">
        <description lang="en"><![CDATA[OVERLAY_DESCRIPTION]]></description>
        <owner type="project">

            Optional (this is an example because it's hard to template it):

            <source type="git"></source>
            <source type="git">git://</source>
            <source type="git"></source>

Once again, don't forget that all of these files have the same exact content, and no, it cannot be a symlink AFAIK

Step six -- Profiles

You only need one file in the profiles folder -- repo_name, the content of it should be your overlay name, for example:


This is the repo_name content on my own overlay, basically the template is

<overlay name>

Step seven -- Readme is an optional file, it's just used for information to give to users, it can have any content but here's a nice template:

# <overlay name>

> <overlay description>

## Installation

### Manual

$ sudo mkdir -p /etc/portage/repos.conf
$ sudo cp <overlay name>.conf /etc/portage/repos.conf/<overlay name>.conf
$ sudo emerge --sync '<overlay name>'

### Eselect repository

$ sudo eselect repository add '<overlay name>' '<overlay sync method (e.g. git)>' '<overlay sync url>'
$ sudo eselect repository enable '<overlay name>'
$ sudo emerge --sync '<overlay name>'

And once you get into the Offical Gentoo API, for example Like I did you also add how to add your overlay through layman:

### Layman

$ sudo layman -a '<overlay name>'
$ sudo layman -s '<overlay name>'

Step eight -- Sets

This directory is optional, although you can have sets of packages in there, like have you ever heard a term called 'world set', it's the same thing, just on your own overlay

Read more about it here

Step nine -- Sets configuration

This file is needed unlike the sets directory, you should have this content in it, although once again, please don't forget to fill in the template:

[<overlay name> sets]
class = portage.sets.files.StaticFileSet
multiset = true
directory = ${repository:<overlay name>}/sets/

Step ten -- Portage overlay configuration

This file, although optional, will help the users of your overlay so much, they can just download this file, put it in /etc/portage/repos.conf/<repo name>.conf and then run

sudo emerge --sync '<repo name>'

And they have it installed, anyway, this is what that file should have

[<overlay name>]
location = /var/db/repos/<overlay name>
sync-type = <overlay sync type>
sync-uri = <overlay sync url>

E.g. for git it'd be:

[<overlay name>]
location = /var/db/repos/<overlay name>
sync-type = git
sync-uri = https://some.git.service/me/my-overlay.git


And that's it, you can now publish your overlay on for example GitHub, like I did on, it's very easy, if you are confused about anything, refer to that repo yourself