beeware / beeware/briefcase

Custom icon apparently packaged, but not found when the app launches

Open
#2,871 1 comment 0 reactions 0 assignees View on GitHub
bug linux
Dominant language
Python
Stars
3.3k
Forks
549
Avg merge
1d 4h
Merged PRs (30d)
40

Description

### Describe the bug

When I add an icon to my Briefcase app, it appears to be packaged correctly, but does not display on the running app, which logs `WARNING: Can't find app icon; falling back to default icon`.

### How to reproduce the bug

1. Install Briefcase (I used a virtualenv on Linux Mint 22.3, Python 3.12.3)
2. Add an icon according to [the "Customizing icons" tutorial](https://tutorial.beeware.org/tutorial/topics/custom-icons/)
3. `briefcase run --update-resources -r`

### Minimum example code

```pyproject.toml
# This project was generated with 0.4.2 using template: https://github.com/beeware/briefcase-template @ v0.4.2
[tool.briefcase]
project_name = "Hello World"
bundle = "com.zacharyspector"
version = "0.0.1"
url = "https://zacharyspector.com/helloworld"
license = "BSD-3-Clause"
license-files = ["LICENSE"]
author = "Zachary Spector"
author_email = "public@zacharyspector.com"

[tool.briefcase.app.helloworld]
formal_name = "Hello World"
description = "My first application"
long_description = """More details about the app should go here.
"""
icon = "icons/helloworld"
sources = [
"src/helloworld",
]
test_sources = [
"tests",
]

requires = [
"faker",
"httpx",
]
test_requires = [
"pytest",
]

```

I have omitted the remainder of `pyproject.toml` because it's the stock template with no changes at all. `src/helloworld/__main__.py` is similarly uninteresting, being the result of [tutorial 8](https://tutorial.beeware.org/tutorial/tutorial-8/).

### Screenshots

Image

### Environment details

- Operating system and version: Linux Mint 22.3
- Python version: 3.12.3
- Software versions:
- Briefcase: 0.4.2
- Toga: 0.5.4

### Logs

```shell
(beeware-venv) sanotehu@zack-ThinkPad-X220:~/src/beeware-tutorial/helloworld$ briefcase run --update-resources -r

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating requirements...
Collecting faker
Using cached faker-40.21.0-py3-none-any.whl.metadata (16 kB)
Collecting httpx
Using cached httpx-0.28.1-py3-none-any.whl.metadata (7.1 kB)
Collecting toga-gtk~=0.5.0
Using cached toga_gtk-0.5.4-py3-none-any.whl.metadata (3.6 kB)
Collecting pygobject<3.52.1
Using cached pygobject-3.50.2-cp312-cp312-linux_x86_64.whl
Collecting packaging (from toga-gtk~=0.5.0)
Using cached packaging-26.2-py3-none-any.whl.metadata (3.5 kB)
Collecting pycairo>=1.17.0 (from toga-gtk~=0.5.0)
Using cached pycairo-1.29.0-cp312-cp312-linux_x86_64.whl
Collecting toga-core==0.5.4 (from toga-gtk~=0.5.0)
Using cached toga_core-0.5.4-py3-none-any.whl.metadata (4.0 kB)
Collecting travertino==0.5.4 (from toga-core==0.5.4->toga-gtk~=0.5.0)
Using cached travertino-0.5.4-py3-none-any.whl.metadata (3.0 kB)
Collecting anyio (from httpx)
Using cached anyio-4.13.0-py3-none-any.whl.metadata (4.5 kB)
Collecting certifi (from httpx)
Using cached certifi-2026.5.20-py3-none-any.whl.metadata (2.5 kB)
Collecting httpcore==1.* (from httpx)
Using cached httpcore-1.0.9-py3-none-any.whl.metadata (21 kB)
Collecting idna (from httpx)
Using cached idna-3.18-py3-none-any.whl.metadata (6.1 kB)
Collecting h11>=0.16 (from httpcore==1.*->httpx)
Using cached h11-0.16.0-py3-none-any.whl.metadata (8.3 kB)
Collecting typing_extensions>=4.5 (from anyio->httpx)
Using cached typing_extensions-4.15.0-py3-none-any.whl.metadata (3.3 kB)
Using cached toga_gtk-0.5.4-py3-none-any.whl (79 kB)
Using cached toga_core-0.5.4-py3-none-any.whl (167 kB)
Using cached travertino-0.5.4-py3-none-any.whl (27 kB)
Using cached faker-40.21.0-py3-none-any.whl (2.0 MB)
Using cached httpx-0.28.1-py3-none-any.whl (73 kB)
Using cached httpcore-1.0.9-py3-none-any.whl (78 kB)
Using cached h11-0.16.0-py3-none-any.whl (37 kB)
Using cached anyio-4.13.0-py3-none-any.whl (114 kB)
Using cached idna-3.18-py3-none-any.whl (65 kB)
Using cached typing_extensions-4.15.0-py3-none-any.whl (44 kB)
Using cached certifi-2026.5.20-py3-none-any.whl (134 kB)
Using cached packaging-26.2-py3-none-any.whl (100 kB)
Installing collected packages: typing_extensions, travertino, pycairo, packaging, idna, h11, faker, certifi, toga-core, pygobject, httpcore, anyio, toga-gtk, httpx

Successfully installed anyio-4.13.0 certifi-2026.5.20 faker-40.21.0 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.18 packaging-26.2 pycairo-1.29.0 pygobject-3.50.2 toga-core-0.5.4 toga-gtk-0.5.4 travertino-0.5.4 typing_extensions-4.15.0
Installing app requirements... done

[helloworld] Updating application resources...
Installing icons/helloworld-16.png as 16px application icon... done
Installing icons/helloworld-32.png as 32px application icon... done
Installing icons/helloworld-64.png as 64px application icon... done
Installing icons/helloworld-128.png as 128px application icon... done
Installing icons/helloworld-256.png as 256px application icon... done
Installing icons/helloworld-512.png as 512px application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Building application...
Build bootstrap binary...
make: Entering directory '/home/sanotehu/src/beeware-tutorial/helloworld/build/helloworld/linuxmint/zena/bootstrap'
mkdir -p ../helloworld-0.0.1/usr/bin
cp helloworld ../helloworld-0.0.1/usr/bin
make: Leaving directory '/home/sanotehu/src/beeware-tutorial/helloworld/build/helloworld/linuxmint/zena/bootstrap'
Building bootstrap binary... done
Installing license... done
Installing changelog... done
Installing man page... done
Updating file permissions... done
Stripping binary... done

[helloworld] Built build/helloworld/linuxmint/zena/helloworld-0.0.1/usr/bin/helloworld

[helloworld] Starting app...
===========================================================================
WARNING: Can't find app icon; falling back to default icon
```

### Additional context

I also tried `briefcase create` and it did the same thing.

Contributor guide

Open the contributing guide

Research direction

Reproduce the problem with the provided pyproject.toml and `briefcase run --update-resources -r`, then inspect Briefcase's Linux resource packaging and application-launch icon lookup. Compare the `briefcase create` and `run` paths; done means the packaged custom icon is found at launch without the warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
linux, python
Domain
build-system
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.