PyKotor

A Python library for reading and modifying file formats used by the game Knights of the Old Republic and its sequel.

Table of Contents

• PyKotor
  • Table of Contents
  • Features
  • Requirements
  • Installation
    • Quick Install
    • Standard Install
  • Quick Start
    • Using the Library
    • Using the Tools
  • Available Tools
  • Documentation
  • Contributing
  • License

Features

• Complete file format support for KotOR and TSL game files
• Cross-platform (Windows, macOS, Linux)
• Holocron Toolset for modding and development
• Modern Python (3.8+)
• Type-annotated API with extensive documentation

Requirements

• Python 3.8+
• Windows 7–11, macOS, or Linux
• All common architectures supported (x86, x64, arm64)

Installation

Quick Install

The fastest way to get started is using uvx (no installation required). Install uv from Installing uv, then run tools with --refresh to ensure you're using the latest version:

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uvx --refresh holocrontoolset

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --refresh holocrontoolset

Standard Install

Install the library:

pip install pykotor

Install tools:

pip install holocrontoolset holopatcher kotordiff

Or use pipx for isolated tool installation:

pipx install holocrontoolset
pipx install holopatcher
pipx install kotordiff

Note: The PyKotor CLI is included with the pykotor package and accessible via pykotor or pykotorcli commands.

See CONTRIBUTING.md for development installation. If cloning the repo is slow or stalls, use a shallow clone: git clone --depth 1 <repo-url> (see CONTRIBUTING for details).

Quick Start

Using the Library

from pykotor.resource.type import ResourceType
from pykotor.extract.installation import Installation
from pykotor.resource.formats.tpc import write_tpc

# Load game installation
inst = Installation("C:/Program Files (x86)/Steam/steamapps/common/swkotor")

# Extract a texture
texture = inst.texture("C_Gammorean01")
write_tpc(texture, "./C_Gammorean01.tga", ResourceType.TGA)

Using the Tools

HolocronToolset - GUI editor for KotOR files:

uvx --refresh holocrontoolset

HoloPatcher - Cross-platform TSLPatcher alternative:

uvx --refresh holopatcher --help

PyKotor CLI - Command-line build tool (included with pykotor):

uvx --refresh pykotor --help
# Example: convert 2DA to CSV
uvx --refresh pykotor 2da2csv "path/to/file.2da"

KotorDiff - Compare and generate patches:

uvx --refresh kotordiff
# or if installed via pip/pipx
kotordiff

See individual tool documentation for detailed usage.

Available Tools

| Tool | Description | Documentation | |------|-------------|---------------| | HolocronToolset | Full-featured GUI editor for KotOR files | README | | HoloPatcher | Fast, cross-platform mod installer | README | | PyKotor CLI | Command-line build tool (part of pykotor package) | Docs | | KotorDiff | File comparison and TSLPatcher data generator | README |

Documentation

User Documentation

• Installation & Usage - Detailed library documentation
• Contributing Guide - Development setup and guidelines
• Project Wiki — community documentation (GitHub UI); clone with git submodule update --init wiki to edit wiki/*.md in-tree (see CONTRIBUTING.md)
• PowerShell Setup - Windows PowerShell configuration

Design & Architecture

• Design System Rules - Comprehensive UI design system documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development environment setup
• Code style guidelines
• Testing procedures
• Pull request process

License

This project is licensed under the LGPL-3.0-or-later License.