Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

TextWorld

PyPI version PyPI - Python Version Build Status Documentation Status Join the chat at https://gitter.im/Microsoft/TextWorld

A text-based game generator and extensible sandbox learning environment for training and testing reinforcement learning (RL) agents. Also check out aka.ms/textworld for more info about TextWorld and its creators. Have questions or feedback about TextWorld? Send them to textworld@microsoft.com or use the Gitter channel listed above.

Installation

TextWorld supports Python 3.9/3.10/3.11/3.12 for Linux and macOS systems only at the moment. For Windows users, docker can be used as a workaround (see Docker section below).

Requirements

TextWorld requires some system libraries for its native components. On a Debian/Ubuntu-based system, these can be installed with

sudo apt update && sudo apt install build-essential libffi-dev python3-dev curl git

And on macOS, with

brew install libffi curl git

Note: We advise our users to use virtual environments to avoid Python packages from different projects to interfere with each other. Popular choices are Conda Environments and Virtualenv

Installing TextWorld

The easiest way to install TextWorld is via pip:

pip install textworld

Or, after cloning the repo, go inside the root folder of the project (i.e. alongside setup.py) and run

pip install .

Visualization

TextWorld comes with some tools to visualize game states. Make sure all dependencies are installed by running

pip install textworld[vis]

Then, you will need to install either the Chrome or Firefox webdriver (depending on which browser you have currently installed). If you have Chrome already installed you can use the following command to install chromedriver

pip install chromedriver_installer

Current visualization tools include: take_screenshot, visualize and show_graph from textworld.render.

Docker

A docker container with the latest TextWorld release is available on DockerHub.

docker pull marccote19/textworld
docker run -p 8888:8888 -it --rm marccote19/textworld

Then, in your browser, navigate to the Jupyter notebook's link displayed in your terminal. The link should look like this

http://127.0.0.1:8888/?token=8d7aaa...e95

Note: See README.md in the docker folder for troubleshooting information.

Usage

Generating a game

TextWorld provides an easy way of generating simple text-based games via the tw-make script. For instance,

tw-make custom --world-size 5 --nb-objects 10 --quest-length 5 --seed 1234 --output tw_games/custom_game.z8

where custom indicates we want to customize the game using the following options: --world-size controls the number of rooms in the world, --nb-objects controls the number of objects that can be interacted with (excluding doors) and --quest-length controls the minimum number of commands that is required to type in order to win the game. Once done, the game custom_game.z8 will be saved in the tw_games/ folder.

Playing a game (terminal)

To play a game, one can use the tw-play script. For instance, the command to play the game generated in the previous section would be

tw-play tw_games/custom_game.z8

Note: Only Z-machine's games (*.z1 through *.z8) are supported.

To visualize the game state while playing, use the --viewer [port] option.

tw-play tw_games/custom_game.z8 --viewer

A new browser tab should open and track your progress in the game.

Playing a game (Python + Gym-like API)

Here's how you can interact with a text-based game from within Python using a Gym-like API.

import textworld.gym

# Register a text-based game as a new environment.
env_id = textworld.gym.register_game("tw_games/custom_game.z8",
                                     max_episode_steps=50)

env = textworld.gym.make(env_id)  # Start the environment.

obs, infos = env.reset()  # Start new episode.
env.render()

score, moves, done = 0, 0, False
while not done:
    command = input("> ")
    obs, score, done, infos = env.step(command)
    env.render()
    moves += 1

env.close()
print("moves: {}; score: {}".format(moves, score))

Note: To play text-based games without a Gym-like API, see Playing text-based games with TextWorld.ipynb

Documentation

For more information about TextWorld, check the documentation.

Visual Studio Code

You can install the textworld-vscode extension that enables syntax highlighting for editing .twl and .twg TextWorld files.

Notebooks

Check the notebooks provided with the framework to see what you can do with it. You will need the Jupyter Notebook to run them. You can install it with

pip install jupyter

Citing TextWorld

If you use TextWorld, please cite the following BibTex:

@Article{cote18textworld,
  author = {Marc-Alexandre C\^ot\'e and
            \'Akos K\'ad\'ar and
            Xingdi Yuan and
            Ben Kybartas and
            Tavian Barnes and
            Emery Fine and
            James Moore and
            Ruo Yu Tao and
            Matthew Hausknecht and
            Layla El Asri and
            Mahmoud Adada and
            Wendy Tay and
            Adam Trischler},
  title = {TextWorld: A Learning Environment for Text-based Games},
  journal = {CoRR},
  volume = {abs/1806.11532},
  year = {2018}
}

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

License

Metadata

Release files for textworld 1.8.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for textworld 1.8.0rc1
File Size Uploaded Provenance Actions
textworld-1.8.0rc1.tar.gz 514.2 kB With provenance Details for textworld-1.8.0rc1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for textworld 1.8.0rc1
File Interpreter ABI Platform Actions
textworld-1.8.0rc1-py3-none-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl Python 3 none Linux glibc 2.5+ x86-64, Linux glibc 2.17+ x86-64 Details for textworld-1.8.0rc1-py3-none-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl
textworld-1.8.0rc1-py3-none-macosx_10_13_x86_64.whl Python 3 none macOS 10.13+ x86-64 Details for textworld-1.8.0rc1-py3-none-macosx_10_13_x86_64.whl

Total release size: 8.9 MB

Release files / textworld-1.8.0rc1.tar.gz

Download URL textworld-1.8.0rc1.tar.gz
Size 514.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1be71857ae701b52ca9e57ed013f83547de869d8b6369f59f87c95bdb6065331
BLAKE2b-256 checksum
How to use checksums
6555bf7850bc73670b0f2ab5c84f14f70434942c833cd7daf84959ccb286a083
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / textworld-1.8.0rc1-py3-none-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl

Download URL textworld-1.8.0rc1-py3-none-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl
Size 4.4 MB
Tags Linux glibc 2.17+ x86-64 Linux glibc 2.5+ x86-64 Python 3
SHA-256 checksum
How to use checksums
66559381fc641d7fcab05ed73a0f06b31ffd89812c9129fc78b6494c3e9b58e1
BLAKE2b-256 checksum
How to use checksums
25fee44cf0f358da6bad014e309895add9604e50002f6affd8482e80b038329d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / textworld-1.8.0rc1-py3-none-macosx_10_13_x86_64.whl

Download URL textworld-1.8.0rc1-py3-none-macosx_10_13_x86_64.whl
Size 4.0 MB
Tags Python 3 macOS 10.13+ x86-64
SHA-256 checksum
How to use checksums
dd63880b4512a5a4f6442bb60d1cbcd3227511a9b73117018c345954d4687034
BLAKE2b-256 checksum
How to use checksums
ce09e4f6a9109f827de575ee6e369ba412e1874153b2669f86a0dae15b85c38a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for textworld 1.8.0rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Select from 3 files

Attestation for textworld-1.8.0rc1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page