ioschmid02 / chatgpt-history-export-to-md

A Python script to effortlessly extract and format your ChatGPT conversations data export from JSON files to well-structured markdown files, with YAML metadata headers. And it all happens locally !

Your entire ChatGPT data in beautiful Markdown

Welcome to the ChatGPT Conversations to Markdown converter! This Python script helps you to convert your entire ChatGPT history and data export into neatly formatted Markdown files.

It adds YAML headers (optional, included by default), and also includes Code interpreter (Advanced Data Analysis) input / output.

See Examples : Screenshot, Markdown, Markdown with dollar signs, Chat link.

Quick setup

See Prerequisites. (just Python and Git and you're good to go. No external dependencies !)

Step 1: Clone the Repository 📥

Open a terminal or command prompt and run the following command:

git clone https://github.com/mohamed-chs/chatgpt-history-export-to-md.git

Next, navigate to the project directory by using the following command:

cd chatgpt-history-export-to-md

Step 2: Download Your Conversations data 🗂

Before you run the script, make sure your ChatGPT conversations are in a ZIP file format.

How to download : (click to expand/collapse)

---

1. Sign in to ChatGPT at https://chat.openai.com

2. At the bottom of the left side bar, click on your profile name, the on Settings

   

3. Go to Data controls

   

4. In the "Data Controls" menu, click on Export data : Export

   

5. In the confirmation modal click Confirm export

   

6. You should get an email with your data, in 2 ~ 5 minutes (check your inbox)

   

7. Click Download data export to download a .zip file containing your entire chat history and other data.

   

   ↑ Collapse

---

The script will automatically find the most recent ZIP file in your 'Downloads' directory (in ~/Downloads/), but you can specify a different file or location if necessary.

Step 3: Running the Script 🏃‍♂️

In the terminal or command prompt, run the script with this command:

python main.py

The default output location for the Markdown files is : ~/Documents/ChatGPT-Conversations/MD/. The script will automatically create the directories if they didn't exist. Feel free to customize the script's behavior.

Step 4: Check the Output 🎉

And that's it! After running the script, check the output folder for your neatly formatted Markdown files.

• a tweet should be fun when I later add the actual data visualizations. Feel free to implement your own data visualizations here, and create a pull request, then check this box (I know you want to)

Optional: Customize the Script's behavior 🌟

command line parameters

Feel free to customize the script's behavior using additional parameters:

• --out_folder: Specify the output folder where the MD files will be saved.
• --zip_file: Specify the ZIP file containing the ChatGPT conversations to be converted.

Here is an example command:

python main.py --out_folder "Obsidian_Vault/Chats" --zip_file "My downloads/my_chat.zip"

This will extract and look for the conversations.json file in ~/My downloads/my_chat.zip, and create the MD files in ~/Obsidian_Vault/Chats.

(on Windows, ~/ refers to C:/Users/{your_username}/).

config.json

You can also modify the config.json file, to customize the output :

{
  "system_title": "System",
  "user_title": "YOUR NAME",
  "assistant_title": "My AI",
  "tool_title": "Code output (or plugin name)",
  "delimiters_default": true
}

Change "delimiters_default" to false to replace all $\LaTeX$ bracket delimiters : \(...\) and \[...\], with dollar sign ones : $...$ and $$...$$, if you'd like your math to render beautifully in Markdown readers that support MathJax (like Obsidian).

You can also configure the YAML header in the config.json to add or remove fields.

Issues and contributions 🆘

See CONTRIBUTING.md.

Feel free to fork this repository and make your enhancements or improvements. ALL contributions are welcome !

If you encounter any issues or have questions, feel free to open an issue / discussion. See also : HN post.

Enjoy Your Conversations in Markdown! 🎈

Hopefully, you find value in this tool. If you do, giving it a star ⭐ on the repository would mean a lot. Thank you!

Prerequisites

Make sure you have Python (version >= 3.10), and Git installed. You can download them from :

• Official Python website
• Official Git website

Yep, no external dependencies needed.

TODO

Doing what needs to be done.

Feel free to add or check items.

general

• keep external dependencies to a minimum (0 so far)
• Javascript to download more conversations, see Javascript
• Add new downloaded conversations to the MD folder
• Update past conversations if changed
• More robust testing setup
• Data visualizations : chat times, frequency, models, word clouds, etc...
• Data analysis : categories and more classifications based on topics, concepts, programming tools, etc ...
• Integration with Obsidian (folders and subfolders, tags, ...)
• Add HTML as an output option
• Format more content data, for example : plugin use
• Support different response selections in a chat
• Extract more data from the JSON files, like user feedback per message
• Option to add metadata for each individual message
• more todos ...

command line

• Nicer command line output formatting
• More configs from the command line (overwrite the config.json)
• Link to submit issues or feedback
• more todos ...

configs.json

• change user, assistant, and system names
• yaml header elements
• specific configs for each individual conversation / conversation type
• output folder (currently set by default or via command line arguments)
• more configs ...

See also : JavaScript Todo

Notes

This is just a small thing I coded to help me see my convos in beautiful markdown, in Obsidian (my note-taking app).

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

I'm working on automating it to add new conversations and updating old ones. Had some luck with a JavaScript bookmarklet, still ironing it out tho. Shouldn't take long.

Star History

Donate ❤️

Thank you for considering supporting a student's modest open source work !