# Icons

To customize the branding of your compiled application, you can include platform-specific icon files in the root of your repository. The `package` pipeline automatically detects and applies them during the bundling process.

#### Icon Asset Requirements

Ensure your asset files match these exact file names and format requirements:

* **macOS Bundle Icon:** `icon.icns` (placed in the project root directory)
* **Windows Executable Icon:** `icon.ico` (placed in the project root directory)

#### Platform-Specific Processing Details

**macOS Configuration**

When building for macOS, the packager updates the `Info.plist` bundle metadata to map its icon resources:

```xml
<key>CFBundleIconFile</key>
<string>icon</string>
```

The file structure inside your generated `.app` bundle automatically maps to expect an asset compiled with this key in its standard system path.

**Windows Binary Resource Injection**

For Windows applications, the pipeline uses **ResEdit** to safely modify the PE (Portable Executable) headers of your renamed application executable.

#### Step-by-Step Asset Setup

{% stepper %}
{% step %}
**Generate Assets**

&#x20;Create your high-resolution artwork and export them to `.icns` and `.ico` containers using your preferred design tool or asset compiler.
{% endstep %}

{% step %}
**Placement**

Copy the completed files directly to your workspace root directory:

<pre><code>my-positron-app/
├── bin/
├── index.js
├── package.json
<strong>├── icon.ico   &#x3C;-- Added here for Windows builds
</strong><strong>└── icon.icns  &#x3C;-- Added here for macOS builds
</strong></code></pre>

{% endstep %}

{% step %}
**Execution**

Trigger your standard pipeline script:

{% code lineNumbers="true" %}

```bash
npx positron package
```

{% endcode %}
{% endstep %}
{% endstepper %}

> **Note:** If an icon file is missing during a build iteration, the script will log a warning (`Skipping icon injection...`) and complete the executable compilation process with standard default system icons rather than throwing a fatal build error.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/cli/package/icons.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.