ChatGPT to Markdown

A tool-first CLI that converts ChatGPT exports into a structured, searchable, offline-friendly Markdown knowledge archive.

Elevator Pitch

chatgpt-to-markdown turns your ChatGPT export into clean Markdown you can read, index, and keep long term. Instead of browsing a raw ZIP or JSON partitions, you get a portable archive with conversation pages, media resolution, metadata files, and index pages, ready for local browsing, static hosting, or personal knowledge management workflows.

---

Project under active development.

chatgpt-to-markdown is still under active development. Not all possible ChatGPT export variants and edge-case output structures are covered yet.

Please validate the generated Markdown archive before relying on it as your only source of truth, and please report issues (with repro details when possible) so we can make the tool more robust and feature-complete.

For safety and recoverability, keep your original ChatGPT export ZIP stored securely. As issues are fixed, you can regenerate the output from that source to pick up improvements.

---

Features

• Parses all conversations-*.json partitions with Pydantic v2 validation
• Walks message DAGs to linearise conversation threads (handles branches and cycles)
• Resolves file-service:// and sediment:// asset pointers against the export manifest
• Renders conversations to Markdown with YAML front matter via Jinja2 templates
• Generates index files for conversations, DALL-E generations, and metadata
• Deduplicates media by SHA-256 hash
• Supports 12+ content types with a fallback for unknown types
• Optional PII redaction for user metadata
• Optional inclusion of thinking/reasoning blocks from o-series models
• Accepts both extracted directories and ZIP files as input

Installation

Run without installing

uvx chatgpt-to-markdown --help

Convert a ChatGPT export ZIP or extracted directory to a Markdown archive:

# From ZIP file
uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive_zip

# From extracted directory
uvx chatgpt-to-markdown ./chatgpt-export ./archive

Install as a global CLI tool with uv (recommended for frequent use)

uv tool install chatgpt-to-markdown

Development install (contributors)

git clone https://github.com/difegam/chatgpt-to-markdown.git
cd chatgpt-to-markdown
uv sync --all-groups

Usage

# Run without installing (ephemeral env)
uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive

# Or use the installed global CLI
chatgpt-to-markdown ./chatgpt-export.zip ./archive

# Convert an extracted export directory
uvx chatgpt-to-markdown ./my-export ./archive

# Convert a ZIP file directly
uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive

# With options
uvx chatgpt-to-markdown ./my-export ./archive --no-redact-pii --include-thinking

# From a local repository checkout (contributors)
uv run chatgpt-to-markdown ./my-export ./archive

CLI Options

Option	Default	Description
input_dir	required	Path to extracted ChatGPT export directory or ZIP file
output_dir	required	Path to output Markdown archive directory
--redact-pii / --no-redact-pii	True	Redact PII (email, phone, birth year) in metadata
--include-thinking	False	Include thinking/reasoning blocks from thinking models
--deduplicate / --no-deduplicate	True	Deduplicate assets by SHA-256 hash

Output Structure

archive/
├── index.md
├── conversations/
│   ├── index.md
│   └── 2024-08-24_test-chat_17cd7535/
│       ├── index.md
│       ├── media/
│       │   └── 001-a1b2c3d4.jpeg
│       └── attachments/
│           └── document.pdf
├── dalle/
│   ├── index.md
│   └── *.webp
└── metadata/
    ├── user_profile.md
    ├── settings.md
    ├── feedback.md
    └── export_stats.md

Development

just init    # Install dependencies and pre-commit hooks
just test    # Run tests
just check   # Run all quality checks
just docs    # Serve docs locally

See CONTRIBUTING.md and the documentation for full development guides.

Publishing

This repository includes .github/workflows/publish.yml for PyPI trusted publishing with uv.

Reference: Building and publishing a package using uv

1. Create the pypi environment in GitHub: Settings → Environments → New environment.

2. In PyPI, add a Trusted Publisher for this project with:

   • Owner: difegam
   • Repository: chatgpt-to-markdown
   • Workflow: publish.yml
   • Environment: pypi

3. Create and push a version tag:

   git tag -a v0.1.0 -m "v0.1.0"
   git push --tags

4. The Publish workflow runs and executes uv build and uv publish.