Skip to content

Add a known issues note into README.md related to QEMU #505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 3, 2025
Merged

Add a known issues note into README.md related to QEMU #505

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,20 @@ Example:
$ bundle exec bootsnap precompile --gemfile app/ lib/ config/
```

## Known issues

### QEMU environments

When building cross-platform Docker images, QEMU is often used for emulation and can be the source of a limitation that causes forked processes to hang. While Bootsnap includes automatic detection for this issue (as of [PR #501](https://github.com/Shopify/bootsnap/pull/501)), the detection may not always be sufficient.

If you encounter hangs during precompilation in QEMU-based environments (such as when using Docker buildx for cross-platform builds), you can work around this by disabling parallelization with the `-j 0` option:

```bash
$ bundle exec bootsnap precompile -j 0 --gemfile app/ lib/ config/
```

See [Issue #495](https://github.com/Shopify/bootsnap/issues/495) for more details about this QEMU-related issue.

## When not to use Bootsnap

*Alternative engines*: Bootsnap is pretty reliant on MRI features, and parts are disabled entirely on alternative ruby
Expand Down