Install without Python experience

Install without Python experience

You may not need to install anything at all

If you just want to look up pronunciations occasionally, the free online tool at rianthai.pro/thai-transliteration runs thaiphon in your browser — no Python, no terminal, no setup. Paste Thai text and get all three transcription schemes instantly.

This install guide is for people who need more than the online tool offers: batch processing of many words, integration into a custom app, or offline use without an internet connection.

This guide walks you through getting thaiphon working on your computer from scratch. It assumes you have never installed Python before and have never used a terminal. You will need about fifteen minutes.

Already comfortable with pip?

If you know Python and pip, go to the standard install guide instead.

Step 1 — Install Python

thaiphon requires Python 3.10 or newer.

  1. Open a web browser and go to python.org/downloads.
  2. Click the large yellow Download Python 3.x.x button. The site detects your operating system automatically.
  3. Run the installer you downloaded.

On Windows — critical step: At the first screen of the installer, check the box that says "Add Python to PATH" before clicking Install Now. If you miss this, Python will install but the terminal will not find it.

On macOS: Run the downloaded .pkg file and follow the prompts. If your Mac asks whether to allow the installation, click Allow.

On Linux: Python 3 is likely already installed. Open a terminal and type python3 --version. If you see a version number 3.10 or higher, skip to Step 2.

Step 2 — Open a terminal

A terminal (also called a command prompt or command line) is a text window where you type instructions.

Press the Windows key, type cmd, and press Enter. A black window opens. This is your terminal.

Alternatively: press Windows key + R, type cmd, press Enter.

Press Command + Space, type Terminal, press Enter.

Or: open Finder → Applications → Utilities → Terminal.

You likely know how to do this already. Common shortcut: Ctrl + Alt + T.

Step 3 — Verify Python is installed

In the terminal, type the following and press Enter:

python --version

python3 --version

You should see something like Python 3.12.0. If you see an error, go back to Step 1 and make sure you checked "Add to PATH" on Windows, or repeat the macOS installer.

Step 4 — Install thaiphon and the lexicon package

In the same terminal window, type this and press Enter:

pip install thaiphon thaiphon-data-volubilis

pip3 install thaiphon thaiphon-data-volubilis

You will see lines of text as the packages download and install. Wait until you see lines that include Successfully installed thaiphon and Successfully installed thaiphon-data-volubilis.

Why two packages?

thaiphon is the engine. thaiphon-data-volubilis is a separate Thai lexicon derived from the VOLUBILIS Mundo Dictionary. Installing both raises accuracy from ~57% to ~75% on an independent Wiktionary benchmark. The engine detects the lexicon automatically — no extra steps needed.

If you see a "permission denied" error on macOS/Linux, try: 

pip3 install --user thaiphon thaiphon-data-volubilis

Step 5 — Test it works

Still in the terminal, start Python:

python

python3

You will see three >>> symbols. This is the Python prompt. Type the following lines, pressing Enter after each one:

import thaiphon
print(thaiphon.transcribe("สวัสดี", format="html"))
print(thaiphon.transcribe("ข้าวผัด", scheme="ipa"))

You should see something like: 

sa<sup>L</sup> wat<sup>L</sup> dee<sup>M</sup>
/kʰaːw˥˩.pʰat̚˨˩/

If the lexicon package is installed correctly, compound words like ข้าวผัด (fried rice) will be segmented and transcribed accurately.

Type exit() and press Enter to leave Python.

Step 6 — Create a script file

Typing into the Python prompt works for quick tests, but for regular use it's better to write a script file.

  1. Open Notepad (Windows) or TextEdit (macOS) or any plain-text editor.
  2. Copy and paste the following:
from thaiphon import transcribe

# List of Thai words to transcribe.
words = ["สวัสดี", "น้ำ", "ข้าว", "รัก", "ปลา"]

for word in words:
    result = transcribe(word, scheme="ipa")
    print(f"{word}  →  {result}")

  1. Save the file as my_transcriber.py on your Desktop or in a folder you can find easily. Make sure the file name ends with .py and the encoding is UTF-8 (in Notepad, choose "UTF-8" from the Encoding dropdown when saving).

  2. In the terminal, navigate to where you saved the file. On Windows: 

    cd Desktop
    On macOS: 
    cd ~/Desktop

  3. Run the script: === "Windows" 

    python my_transcriber.py
    === "macOS / Linux" 
    python3 my_transcriber.py

Expected output: 

สวัสดี  →  /sa˨˩.wat̚˨˩.diː˧/
น้ำ  →  /naːm˦˥/
ข้าว  →  /kʰaːw˥˩/
รัก  →  /rak̚˦˥/
ปลา  →  /plaː˧/

Common problems

The terminal shows "Thai characters" as boxes or question marks.

Your terminal may not support Thai script display. This does not mean thaiphon is broken — the transcription is calculated correctly. You can write the output to a text file instead:

with open("output.txt", "w", encoding="utf-8") as f:
    f.write(transcribe("สวัสดี", scheme="ipa"))

Then open output.txt in a text editor that supports Unicode (most modern editors do).

Pasting Thai text loses the tone marks.

Some applications change the encoding when copying and pasting. Use a Unicode-aware editor (VS Code, Notepad++, BBEdit) and make sure the file is saved as UTF-8.

I see ModuleNotFoundError: No module named 'thaiphon'.

Python found but thaiphon is not installed in that Python's environment. Check which Python you used to install (pip --version shows the associated Python) and which one you used to run the script. On some systems multiple Python versions coexist. Try pip3 install thaiphon or python3 -m pip install thaiphon.

I see SyntaxError on the first line.

This usually means you are running Python 2 instead of Python 3. Check your version with python --version. thaiphon requires 3.10 or newer.

Next steps