# Contribute

## Forking Arcticons

* Go to the GitHub page <https://codeberg.org/Arcticons/Arcticons-Linux/> in a browser.
* In the top-right corner, click the **Fork** button. You'll get your very own clone of Arcticons! (You need a GitHub account for this).

I'd recommend using [GitHub Desktop ](https://github.com/apps/desktop)to make Git less difficult.

* Download & Install GitHub Desktop, and login with your credentials
* Click on `Add > Clone repository` and select your Arcticons repo. This will create a folder with the Arcticons project.

Now you have your local Arcticons project. This means you can add icons and edit the `mappings.yaml`.

## Preparing the codebase

For generating the icons, you may need to do a `git submodule init` followed by `git submodule update` to pull the Arcticons repo, which will be pulled into the `.arcticons` folder.

We are using [uv](https://docs.astral.sh/uv/) for the dependency management of the Python scripts. Run `uv sync --dev` in the Arcticons-Linux repo folder to prepare the environment.

## Contributing your own icons

To contribute icons, which don't fit into the Android icon pack, you can place them into the `icons_linux` folder.

For matching the Arcticons style, you can follow the Android creation guide here:

{% content-ref url="../../contribute/creating-icons" %}
[creating-icons](https://docs.arcticons.com/contribute/creating-icons)
{% endcontent-ref %}

You need to export the icon with black lines (stroke color `#000`) inside the `icons_linux` folder.

## Mapping the icons

Under Linux, there is no single nomenclature for the app names, and so the icons are often needed in multiple places to account for different packaging systems etc.

For that, we have a mapping file called `mapping.yaml`, in which the icon names are mapped to different destinations.

Here is an example of a mapping:

```yaml
browser:
  - apps/org.gnome.Epiphany
  - categories/applications-internet
  - categories/applications-network
```

The `browser` icon is mapped to three destinations. To add a new icon, just add the icon name as a new section and then the destination(s) as a list.

You can run `uv run scripts/validate_mapping.py` to validate the mapping file for correct syntax.

### Finding the icons

Unfortunately, there are multiple locations for icons on Linux.

One way to find them (on KDE), is by opening the properties for the app.

1. The name should match with the name inside the mappings.yaml file.
2. The prefix to the name corresponds to the location of the app.

<figure><img src="https://1579052187-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2RrVVBRQ3dxPE4yo9gYS%2Fuploads%2FAy6UgTxj9vAsC0ruejS8%2FScreenshot_20250427_110149-1.png?alt=media&#x26;token=ee41c6b7-1357-41ab-94e5-438adfe9162c" alt="" width="348"><figcaption></figcaption></figure>

There is also an icon search script which helps to find mappings.

Run `uv run scripts/icon_search.py <keyword>` to find icons containing the keyword as well as desktop files. This searches the most common places. You can use the parameters `-v` to see from which files the mappings were found, `--no-icons` to only search desktop files and `--no-desktop` to only search icon folders.

## Generating icons

Run `uv run scripts/generate_icons.py -c generate-icons.toml` to generate the icons.

## Necessary information for a PR

### New icons

* You can create a PR as soon as you place the new icons inside the `icons_linux` directory. If you don't want to edit the mapping file, you can just give the mapping in the PR description.
* You can edit the mapping file to include the mappings just at the bottom of the file. While generating the icons, the mapping file will be sorted automatically.
* If you like, you can also generate the icons on your machine to include them in the PR. Be aware that for this to work, you need to have the main Arcticons repo pulled as the submodule; additionally, you need to have *Inkscape* installed.

### New mappings

* If adding the mapping an icon which doesn't exist yet in the mapping file, adding it to the bottom of the file is perfectly fine, it will be sorted automatically when generating the icons.
* If adding a mapping to an icon which is already in the file, you can add the mapping to the list. It will be sorted automatically when generating the icons.
* If you like, you can also generate the icons on your machine to include them in the PR. Be aware that for this to work, you need to have the main Arcticons repo as pulled as submodule; additionally, you need to have *Inkscape* installed.

## Uploading to GitHub

Now, when you open your GitHub Desktop window, you'll see a summary of the changes that you've made.&#x20;

1. Give your commit a small summary.
2. Press the Current branch button, then create a new branch. Give it a name and press Create.
3. Publish your branch and commit the changes.
4. Now you can create a pull request by pressing the button. This will open the GitHub site again.
5. Create your pull request and you're done!

There you go, now all you have to do is wait for it to be merged into the Linux theme.