Skip to content
​TextWorld is a sandbox learning environment for the training and evaluation of reinforcement learning (RL) agents on text-based games.
Python Jupyter Notebook JavaScript C Shell CSS Other
Branch: master
Clone or download
MarcCote Merge pull request #177 from microsoft/type-determinism
logic: Make types iterate in a deterministic order
Latest commit 0e15855 Aug 16, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis Addin pydot as a dependency Oct 25, 2018
benchmark Import the TextWorld code Jul 12, 2018
docker Remove uuid.h dependency Dec 11, 2018
misc Import the TextWorld code Jul 12, 2018
notebooks Fix directory to games Feb 16, 2019
scripts Add meaningful error message when wrong --theme is specified Aug 14, 2019
src glk: Create the socket name race-free Jan 31, 2019
tests Forcing --entity-numbering for tw-coin_collector May 8, 2019
textworld logic: Make types iterate in a deterministic order Aug 16, 2019
tools Remove architecture-specific files from the sdist Feb 8, 2019
.gitignore New script to build all the distributed packages Feb 7, 2019
.travis.yml Remove uuid.h dependency Dec 11, 2018 logic: Don't expand rules until we're matching May 22, 2019 Import the TextWorld code Jul 12, 2018
LICENSE.txt Import the TextWorld code Jul 12, 2018 Remove architecture-specific files from the sdist Feb 8, 2019 minor Apr 12, 2019 Import the TextWorld code Jul 12, 2018
delete_rewritten_files.ps1 Import the TextWorld code Jul 12, 2018 Remove unused imports Feb 19, 2019
requirements.txt gym: Relax exact version dependency Mar 28, 2019
rewrite_files.ps1 Import the TextWorld code Jul 12, 2018 Preparing for release Dec 7, 2018 Update Jul 5, 2019
tox.ini Import the TextWorld code Jul 12, 2018


Build Status PyPI version Documentation Status Join the chat at

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


TextWorld requires Python 3 and only supports Linux and macOS systems at the moment.


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 and run

pip install .


In order to use the take_screenshot or visualize functions in textworld.render, you'll need to install either the Chrome or Firefox webdriver (depending on which browser you have installed). If you have Chrome already installed you can use the following command to install chromedriver

pip install chromedriver_installer


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.ulx

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.ulx 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.ulx

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

Playing a game (Python + Gym)

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

import gym
import textworld.gym

# Register a text-based game as a new Gym's environment.
env_id = textworld.gym.register_game("tw_games/custom_game.ulx",

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

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

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

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

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


For more information about TextWorld, check the documentation.


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:

  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
            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}


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

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 with any additional questions or comments.

You can’t perform that action at this time.