Skip to content

Getting Started

Jump to bottom
Been012 edited this page Apr 2, 2026 · 2 revisions

Getting Started

A step-by-step guide to get df-storyteller running with your Dwarf Fortress game. No programming experience needed.

What You Need

  • Dwarf Fortress (Steam version) — the classic free version won't work
  • DFHack — a mod that lets external tools read your game data. Install it from Steam (it's listed as a free separate "game" — click Play, Steam installs it alongside DF)
  • Python 3.11 or newer — a programming language that runs df-storyteller. Download it here

Important: When installing Python, tick the box that says "Add Python to PATH". If you miss this, the commands below won't work.

You do NOT need an AI service or API key. All the core features (portraits, character sheets, event feed, legends browser) work without AI. AI is only needed if you want the tool to write stories for you.

Step 1: Install df-storyteller

Open a terminal:

  • Windows: Press Win+R, type cmd, press Enter
  • Mac: Open Terminal from Applications > Utilities

Type this and press Enter:

pip install df-storyteller

Wait for it to finish downloading. You should see "Successfully installed df-storyteller".

Step 2: Set Up

In the same terminal, type:

df-storyteller init

Windows users: If you see "df-storyteller is not recognized", type python -m df_storyteller init instead (note the underscores). This is a Windows quirk, not a bug.

It will ask you a few questions:

  1. Where is Dwarf Fortress installed? — It usually finds this automatically. If not, paste your DF folder path (e.g. C:\Program Files (x86)\Steam\steamapps\common\Dwarf Fortress)

  2. Which AI provider? — Choose "none" if you just want to explore without AI. You can always add one later in Settings.

That's it for setup. You only do this once.

Step 3: Connect to Your Fortress

  1. Launch Dwarf Fortress normally (with DFHack installed)
  2. Load a save or start a new embark
  3. Open the DFHack console — look for a separate window that opened alongside DF. If you can't find it, try pressing the backtick key (`, the key above Tab on most keyboards)
  4. In the DFHack console, type:
storyteller-begin

You'll see a message listing how many dwarves, visitors, and animals were captured. This runs automatically from now on whenever you load this save — you don't need to type it again.

Step 4: Open the Web Interface

Go back to your terminal (not DFHack) and type:

df-storyteller serve

Your browser should open automatically to http://localhost:8000. If it doesn't, open your browser and go to that address manually.

You'll see your fortress dashboard with dwarf portraits, events, and character sheets. Leave this running while you play — it updates as events happen in your game.

Step 5 (Optional): Export World History

This unlocks the Legends tab — a full browser for your world's history with thousands of historical figures, wars, civilizations, artifacts, and family trees.

  1. In the DFHack console, type: open-legends
  2. DF will switch to the legends viewer screen
  3. Click "Export XML" at the top of the screen
  4. Wait for the export to finish (can take a minute for large worlds)
  5. Press Escape to return to your fortress

The web interface automatically picks up the exported data. Refresh the page and the Legends tab will be populated.

That's It!

Play your game normally. The web interface shows:

  • Dwarf portraits that match their in-game appearance
  • Character sheets with personality, skills, relationships, and equipment
  • Live event feed as things happen (combat, migrations, births, deaths)
  • Combat logs with blow-by-blow fight details
  • Military dashboard with squad stats and kill leaderboards
  • Visitor portraits for traders, diplomats, and poets from other civilizations
  • Animal sprites for your livestock and wild creatures

To write stories, click the Chronicle or Biography tabs. You can write manually or use AI if you configured a provider.

To reference lore in your writing, use double brackets: [[The Fated Arch]] creates a clickable link to that civilization's legends page.

Updating

When a new version is released:

pip install --upgrade df-storyteller

Then restart the web server (Ctrl+C in the terminal, then df-storyteller serve again).

Common Issues

"df-storyteller is not recognized" Use python -m df_storyteller instead of df-storyteller. This happens on some Windows installs.

"No fortress data found" You need to run storyteller-begin in the DFHack console first.

Pages look empty or outdated Restart the web server. Game data is cached for a few minutes.

Events stop appearing after saving The tool handles autosaves automatically. If events stop, type in DFHack:

storyteller-events stop
storyteller-events start

Can't find the DFHack console Make sure DFHack is installed (Steam Workshop is easiest). The console is a separate window — check your taskbar. You can also press ` (backtick) in-game.

Legends tab is empty You need to export world history first. Run open-legends in DFHack, click Export XML, then refresh the web page.

Clone this wiki locally