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.

PyPI Version License Downloads CI Status

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

  1. Sign in at chatgpt.com
  2. Navigate to: Profile Name (bottom left) → Settings → Data controls → Export
  3. Click Confirm export
  4. 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.

  1. Follow the instructions in js/HOW_TO_USE.md to download your recent data as a .zip file.
  2. Run Convoviz normally.
  3. Smart Discovery: If you have a convoviz_export.zip in your Downloads, Convoviz will ask to merge it.
  4. 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

  1. Open Terminal.
    • macOS: Press Cmd + Space, type "Terminal", and hit Enter.
    • Linux: Press Ctrl + Alt + T, or search "Terminal" in your app menu.
  2. Copy and paste this command:
curl -fsSL https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.sh | bash

🪟 Windows

  1. Open PowerShell.
    • Press the Windows key, type "PowerShell", and hit Enter.
  2. 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:

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

Use a custom config path:

convoviz --config path/to/config.toml

Markdown flavor options in config:

  1. standard (default)
  2. obsidian (collapsible callouts for reasoning content)

Markdown render order (config):

  1. active (default, current branch)
  2. 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

💌 Share Your Feedback!

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.

Project links

Data verified by PyPI on Aug 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mohamed-chs from gravatar.com mohamed-chs

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Mohamed Cheikh Sidiya

GitHub Statistics

Data verified by PyPI on Aug 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

viz

Tags

markdown chatgpt openai visualization analytics json export data-analysis obsidian

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

convoviz-0.7.4.tar.gz (2.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

convoviz-0.7.4-py3-none-any.whl (2.0 MB view details)

Uploaded Python 3

File details

Details for the file convoviz-0.7.4.tar.gz.

File metadata

  • Download URL: convoviz-0.7.4.tar.gz
  • Upload date:
  • Size: 2.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for convoviz-0.7.4.tar.gz
Algorithm Hash digest
SHA256 4152379072f0f76b5e4546c65cca0602774f822cba49f89c3817c74db2cf3749
MD5 6354e31b26d0c74d54ffa5d8707a0030
BLAKE2b-256 6eba11bd177fd6ac4c5a12c9438f6d39af569adc4257c175da6f5071f33b6c2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for convoviz-0.7.4.tar.gz:

Publisher: release.yml on mohamed-chs/convoviz

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file convoviz-0.7.4-py3-none-any.whl.

File metadata

  • Download URL: convoviz-0.7.4-py3-none-any.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for convoviz-0.7.4-py3-none-any.whl
Algorithm Hash digest
SHA256 dde00cbf2690de636accb57e89e34d2e908c9bc5a426474608ab09d23e45238b
MD5 36e18d9c6f174812f23e5a9b392c126b
BLAKE2b-256 c8d665e08823aa19cf31d3e8ba157682bff73535b632232b2abea3d88d1b77fe

See more details on using hashes here.

Provenance

The following attestation bundles were made for convoviz-0.7.4-py3-none-any.whl:

Publisher: release.yml on mohamed-chs/convoviz

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.7.4 This release

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page