beeware / beeware/briefcase

`.pth` files located in `app_packages` are not processed

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

Description

### Describe the bug

`.pth` that are located in the `app_packages` folder are not correctly processed on all platforms.

This leads to import errors with some packages. A prominent example is `pywin32` (see [here](https://github.com/beeware/briefcase/issues/381) and [here](https://github.com/beeware/briefcase/issues/835)).

In addition, any Python code can be executed via `.pth` file at startup. This can also be used, for example, to establish a connection with a remote debugger (see [here](https://github.com/beeware/briefcase/issues/2147) and [here](https://github.com/beeware/briefcase/pull/2173)).

The following platforms are affected by this:
- Windows App
- Windows VisualStudio
- Linux Flatpak
- Linux System
- Linux AppImage (I guess, but I am not 100% sure. I could not test this so far.)
- macOS App
- macOS XCode
- iOS XCode
- Web

The following platforms are not affected by this:
- Android (but there is another bug as noted [here](https://github.com/chaquo/chaquopy/issues/1338))

### Steps to reproduce

Add the following to `pyproject.toml`
```
...
[tool.briefcase.app.helloworld]
requires = [
"git+https://github.com/timrid/pth-execution-checker@main"
]
...
```

and somewhere in the app call

```
import pth_execution_checker
if not pth_execution_checker.pth_executed:
raise RuntimeError(".pth file not processed...")
```

### Expected behavior

`.pth` files should be processed correctly on all platforms.

### Screenshots

_No response_

### Environment

- Operating System: Windows, Linux, macOS
- Python version: 3.13
- Software versions:
- Briefcase: 0.3.22

### Logs

### Additional context

One solution would be to remove `app` and `app_packages` entirely and move all packages to `site-packages`, as described in https://github.com/beeware/briefcase/issues/2195. But this was rejected by @freakboy3742. But he made the following suggestion ([Link](https://github.com/beeware/briefcase/issues/2195#issuecomment-2727821874)):

> The site_packages folder isn't inherently special - it's just on the site list by default because it's a location tied to a the Python interpreter's libdir. The method site.addsitedir() exists to add additional site folders - I'm fairly certain the fix here is to use this method to add app_packages as a site dir, rather than just adding it to PYTHONPATH/sys.path as the stub is currently doing.

Contributor guide

Open the contributing guide

Research direction

Start by locating the platform stubs that add app_packages through PYTHONPATH or sys.path, then compare their behavior with Python's site.addsitedir() suggestion. Reproduce the issue using the pyproject.toml dependency and pth_execution_checker example, and verify that .pth files are processed on each affected platform.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.