Skip to content

Commit f4afd95

Browse files
xronocodexronocode
authored
Add FAQ section on caching cibuildwheel's downloaded tools (#2842)
* Add FAQ section on caching cibuildwheel's downloaded tools Adds a Tips entry covering: - What cibuildwheel caches (CPython/PyPy installers, virtualenv, python-build-standalone archives) and the default per-OS cache folder. - How to override the cache location with ``CIBW_CACHE_PATH``. - A worked GitHub Actions example pairing ``actions/cache`` with ``CIBW_CACHE_PATH`` so the cache survives between runs. - A pointer to ``--clean-cache`` for invalidating stale entries. Closes #1585. Per @joerick's request in the issue ("a caching section in the FAQ would be great, if you can contribute it") the scope is intentionally narrow — just FAQ-level guidance. Platform-specific caching (e.g. Windows NuGet, addressed in #2839) lives in the platforms doc. * docs: bump actions/cache v4 to v5 * docs: move cache to runner.temp, add cache poisoning warning (review feedback)
1 parent 6c08562 commit f4afd95

1 file changed

Lines changed: 45 additions & 0 deletions

File tree

‎docs/faq.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,51 @@ Meson generally works well with cibuildwheel, but there are a few things to be a
102102

103103
- If you need to build 32-bit Windows wheels, you need to activate a 32-bit compiler toolchain before starting cibuildwheel. Many users use [ilammy/msvc-dev-cmd](https://github.com/ilammy/msvc-dev-cmd) for this purpose.
104104

105+
### Caching cibuildwheel's downloaded tools {: #caching}
106+
107+
To speed up builds, cibuildwheel caches the tools it downloads — CPython/PyPy installers, [`virtualenv`][virtualenv], [python-build-standalone][pbs] archives used on Android/iOS, etc. The active cache folder is printed in the preamble of every run:
108+
109+
```
110+
Cache folder: /Users/Matt/Library/Caches/cibuildwheel
111+
```
112+
113+
By default it lives under the OS user-cache directory:
114+
115+
| Platform | Default cache folder |
116+
| ------------ | --------------------------------------------- |
117+
| Linux | `~/.cache/cibuildwheel` |
118+
| macOS / iOS | `~/Library/Caches/cibuildwheel` |
119+
| Windows | `%LOCALAPPDATA%\pypa\cibuildwheel\Cache` |
120+
121+
Set the `CIBW_CACHE_PATH` environment variable to point cibuildwheel at a different folder. On CI you'll typically want a workflow-defined path so that the runner's cache action can persist it between runs.
122+
123+
#### Persisting the cache on GitHub Actions
124+
125+
```yaml
126+
- uses: actions/cache@v5
127+
with:
128+
path: ${{ runner.temp }}/cibw-cache
129+
key: cibw-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}
130+
restore-keys: |
131+
cibw-${{ runner.os }}-
132+
133+
- uses: pypa/[email protected]
134+
env:
135+
CIBW_CACHE_PATH: ${{ runner.temp }}/cibw-cache
136+
```
137+
138+
The `restore-keys` fallback lets a slightly stale cache still be reused if `pyproject.toml` changes. Adjust the cache key to whatever set of inputs determines what cibuildwheel will download (e.g. include a hash of `pyproject.toml`'s `[tool.cibuildwheel]` section, or pin on a Python build-tools version).
139+
140+
For platform-specific notes (e.g. caching the official python.org installers on macOS, or NuGet CPython downloads on Windows), see the [platforms documentation](platforms.md).
141+
142+
If the cache becomes stale or corrupt, run `cibuildwheel --clean-cache` (or simply delete the folder) before re-running.
143+
144+
!!! warning "Cache poisoning security risk"
145+
Use of caching in a release pipeline means the cache folder is now a possible security risk - an attacker could [poison the cache](https://hivesecurity.gitlab.io/blog/github-actions-cache-poisoning-supply-chain/) with executables they have compromised. If you use this for release builds, consider who has access to modify the cache. Specifically be careful if your repo has any workflows using `pull_request_target`, even if they appear unrelated.
146+
147+
[virtualenv]: https://virtualenv.pypa.io/
148+
[pbs]: https://gregoryszorc.com/docs/python-build-standalone/main/
149+
105150
### Automatic updates using Dependabot {: #automatic-updates}
106151

107152
Selecting a moving target (like the latest release) is generally a bad idea in CI. If something breaks, you can't tell whether it was your code or an upstream update that caused the breakage, and in a worst-case scenario, it could occur during a release.

0 commit comments

Comments
 (0)