Skip to content

docs: warn against using Gymnasium FrameStackObservation for image observations #2258

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

Open
midhunxavier wants to merge 1 commit into
base: master
Choose a base branch
from
+11 −1
Open

docs: warn against using Gymnasium FrameStackObservation for image observations #2258

Show file tree
Hide file tree
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
9 changes: 9 additions & 0 deletions docs/guide/custom_env.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,15 @@ Although SB3 supports both channel-last and channel-first images as input, we re
Under the hood, when a channel-last image is passed, SB3 uses a `VecTransposeImage` wrapper to re-order the channels.
:::

:::{warning}
Do not use Gymnasium's `FrameStackObservation` wrapper to stack image frames for SB3.
It adds a new leading dimension (e.g. an image of shape `(3, 64, 64)` becomes `(2, 3, 64, 64)` when stacking 2 frames),
which SB3's `is_image_space` check treats as a non-image (a batch of images) rather than an image.
As a consequence, a `FlattenExtractor` is used instead of a CNN, and the CNN policy is silently not applied.
Use SB3's `VecFrameStack` instead, which stacks frames along the channel dimension and keeps the observation
recognized as an image (see [issue #2090](https://github.com/DLR-RM/stable-baselines3/issues/2090)).
:::

:::{note}
SB3 doesn't support `Discrete` and `MultiDiscrete` spaces with `start!=0`. However, you can update your environment or use a wrapper to make your env compatible with SB3:

Expand Down
3 changes: 2 additions & 1 deletion docs/misc/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@

- Added example for using torch.compile
- Fixed many broken links and updated links to https whenever possible
- Added a warning about using Gymnasium's `FrameStackObservation` with image observations (use `VecFrameStack` instead) (@midhunxavier)

## Release 2.8.0 (2026-04-01)

Expand Down Expand Up @@ -1864,7 +1865,7 @@ And all the contributors:
@lutogniew @lbergmann1 @lukashass @BertrandDecoster @pseudo-rnd-thoughts @stefanbschneider @kyle-he @PatrickHelm @corentinlger
@marekm4 @stagoverflow @rushitnshah @markscsmith @NickLucche @cschindlbeck @peteole @jak3122 @will-maclean
@brn-dev @jmacglashan @kplers @MarcDcls @chrisgao99 @pstahlhofen @akanto @Trenza1ore @JonathanColetti @unexploredtest
@m-abr
@m-abr @midhunxavier

[@adamgleave]: https://github.com/adamgleave
[@araffin]: https://github.com/araffin
Expand Down