Convoviz

uv tool install "convoviz[viz]"

Convert your ChatGPT history into clean, readable Markdown (text files).

Perfect for archiving, local search, or use with note-taking apps like Obsidian.

Visualize your data with word clouds and usage graphs.

Features


Markdown Export	Clean, well-formatted Markdown with optional YAML headers
Inline Images	Media attachments rendered directly in your Markdown files
Citations	Web search results and source links accurately preserved
Word Clouds	Visual breakdowns of your most-used words and phrases
Usage Graphs	Bar plots and charts showing your conversation patterns
Canvas Support	OpenAI "Canvas" documents extracted as standalone files (`.py`, `.html`, etc.)
Custom Instructions	User/Model system messages exported to `custom_instructions.json`

see word cloud examples in the demo/ folder!

How to Use

Step 1: Export Your ChatGPT Data

Sign in at chatgpt.com
Navigate to: Profile Name (bottom left) → Settings → Data controls → Export
Click Confirm export
Wait for the email from OpenAI, then download the .zip file

Alternative: Use the Direct Export Script

If you want to grab recent conversations quickly or bypass the official export wait, use the direct export script.

Follow the instructions in js/HOW_TO_USE.md to download your recent data as a .zip file.
Run Convoviz normally.
Smart Discovery: If you have a convoviz_export.zip in your Downloads, Convoviz will ask to merge it.
Additive & Smart: You can combine multiple runs into the same folder. Convoviz uses identity-based overwriting to update existing chats without creating duplicates!

Step 2: Install Convoviz

Quick Install

Run one of the commands below to install everything you need automatically.

🍎 macOS / 🐧 Linux

Open Terminal.
- macOS: Press Cmd + Space, type "Terminal", and hit Enter.
- Linux: Press Ctrl + Alt + T, or search "Terminal" in your app menu.
Copy and paste this command:

curl -fsSL https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.sh | bash

🪟 Windows

Open PowerShell.
- Press the Windows key, type "PowerShell", and hit Enter.
Copy and paste this command:

irm https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.ps1 | iex

Alternative: Install with pip

If you prefer using pip directly:

# Create a virtual environment (keeps your system Python clean)
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install convoviz with visualization extras
pip install "convoviz[viz]"

Step 3: Run Convoviz

The simplest way is to run this in your terminal and follow the interactive prompts:

convoviz

Or, provide arguments directly to skip the prompts:

convoviz --input path/to/your/export.zip --output path/to/output/folder

Command Line Options

Selective Output

By default, all outputs (Markdown, graphs, word clouds) are generated. Use --outputs to pick specific ones:

convoviz --input export.zip --outputs markdown --outputs graphs

Available options: markdown, graphs, wordclouds

In interactive mode, you'll be prompted to choose which outputs to generate.

Other Useful Flags

Flag	Description
`--zip` / `-z`	Alias for `--input` (for convenience)
`--timestamp` / `-t`	Prepend conversation timestamp to the filename (e.g., `2024-03-21_15-30-05 - Title.md`)
`--no-interactive`	Force non-interactive mode
`--flat`	Put all Markdown files in a single folder (instead of organizing by date)
`--config PATH`	Use a specific TOML config file (otherwise the user config is used if present)
`--verbose` / `-v`	Enable detailed logging (use `-vv` for debug logs)
`--log-file PATH`	Specify a custom log file location
`--quiet` / `-q`	Reduce console output (still logs to file)

For a complete list of options:

convoviz --help

⚙️ Configuration

Convoviz supports a TOML config file. Defaults are bundled with the package and can be copied into your user config directory.

Generate a user config file:

convoviz config init

Default user config locations:

Linux: ~/.config/convoviz/config.toml
macOS: ~/Library/Application Support/convoviz/config.toml
Windows: %APPDATA%\\convoviz\\config.toml

Use a custom config path:

convoviz --config path/to/config.toml

Markdown flavor options in config:

standard (default)
obsidian (collapsible callouts for reasoning content)

Markdown render order (config):

active (default, current branch)
full (all DAG branches)

Markdown timestamps can be toggled with conversation.markdown.show_timestamp.

Word clouds can be limited to your messages by setting wordcloud.include_assistant_text = false. Word cloud layouts are deterministic by default; set wordcloud.random_state = "" to disable.

YAML frontmatter titles are sanitized; the original title is preserved in aliases when it changes.

Step 4: Check the Output

After running the script, head to your output folder (defaults to Documents/ChatGPT-Data if you didn't change it) to see:

Neatly formatted Markdown files
Visualizations and graphs
Extracted Canvas documents (if any)
User "Custom Instructions" (custom_instructions.json)

If you've had a great experience, consider giving the project a ⭐ star! It keeps me motivated and helps others discover it!

Export to PDF

Try convpdf to convert markdown files to PDFs.

Example:

# install with npm
npm -g install convpdf

# go to output dir (defaults to ~/Documents/ChatGPT-Data/)
cd ~/Documents/ChatGPT-Data

# run (add '-j 20' for faster conversion)
convpdf Markdown -o PDF

wordcloud example

I hope you find this tool useful. I'm continuously looking to improve on this, but I need your help for that.

Whether you're a tech wizard or you're new to all this, I'd love to hear about your journey with the tool. Found a quirk? Have a suggestion? Or just want to send some good vibes? I'm all ears!

👉 Open an Issue

Contributing

Interested in contributing? Check out the Contributing Guide for development setup, code style, and how to submit a pull request.

Notes

Offline

Word clouds use NLTK stopwords. If you're offline and NLTK data isn't installed yet, pre-download it:

python -c "import nltk; nltk.download('stopwords')"

NOTE: The install script already handles this, so you can immediately go offline after running it.

About This Project

This is just a small thing I coded to help me see my convos in beautiful markdown. It was originally built with Obsidian (my go-to note-taking app) in mind, but the default output is standard Markdown.

I wasn't a fan of the clunky, and sometimes paid, browser extensions.

It was also a great opportunity to learn more about Python and type annotations. I had mypy, pyright, and ruff all on strict mode, 'twas fun.

Direct Export (Experimental)

There's also a JavaScript export flow under js/ for grabbing additional conversation data directly from the browser outside the official ZIP export. This is experimental.

Metadata

Release files for convoviz 0.7.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for convoviz 0.7.6
File	Size	Uploaded
convoviz-0.7.6.tar.gz	2.0 MB	Sep 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for convoviz 0.7.6
File	Interpreter	ABI	Platform	Reset
convoviz-0.7.6-py3-none-any.whl 2.0 MB Sep 13, 2026	Python 3	none	any	Details

Total release size: 4.0 MB

Release files / convoviz-0.7.6.tar.gz

Download URL	convoviz-0.7.6.tar.gz
Size	2.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`9bb024c2f9cd043007588f194f737c859a2a874cc5ebe9f6b290c1ffd0eef89f`
BLAKE2b-256 checksum How to use checksums	`e9817dc1389dcac9e41fad7a039df4f348335d0ab83fef02cf2ba6f06dc6a767`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mohamed-chs/convoviz
Publishing commit: github.com/mohamed-chs/convoviz/tree/6c22e7398bdceb16c34c974512fc460f7bf642c6

Workflow

Publishing configuration: github.com/mohamed-chs/convoviz/blob/6c22e7398bdceb16c34c974512fc460f7bf642c6/.github/workflows/release.yml
Publishing logs: github.com/mohamed-chs/convoviz/actions/runs/34766542240/attempts/1

Artifact

Subject: convoviz-0.7.6.tar.gz
SHA-256 checksum: 9bb024c2f9cd043007588f194f737c859a2a874cc5ebe9f6b290c1ffd0eef89f Verifying attestations

Release files / convoviz-0.7.6-py3-none-any.whl

Download URL	convoviz-0.7.6-py3-none-any.whl
Size	2.0 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`8b89bfbd64b0b36ecde803819aea201a3e7edae249a73730a371f1bedc3996c8`
BLAKE2b-256 checksum How to use checksums	`ed6368924eed464c83669d3d3b34665caf9f5e54e81f14bfc0b37583a003e7bd`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mohamed-chs/convoviz
Publishing commit: github.com/mohamed-chs/convoviz/tree/6c22e7398bdceb16c34c974512fc460f7bf642c6

Workflow

Publishing configuration: github.com/mohamed-chs/convoviz/blob/6c22e7398bdceb16c34c974512fc460f7bf642c6/.github/workflows/release.yml
Publishing logs: github.com/mohamed-chs/convoviz/actions/runs/34766542240/attempts/1

Artifact

Subject: convoviz-0.7.6-py3-none-any.whl
SHA-256 checksum: 8b89bfbd64b0b36ecde803819aea201a3e7edae249a73730a371f1bedc3996c8 Verifying attestations