· · Building With AI ·Build logs

Migrating from WordPress to Django

Migrating from WordPress to Django
Reading time5 min
Length1,100 words
Last updatedOctober 29, 2026
LevelStep by step

My experience with using Django has grown in leaps and bounds since qualifying in March 2024. All I have done is focused ALL my attention of getting really great at using it for what is now yearly a year. 

As a result I made the decision to migrate my sites from WordPress to Django. This process is only worth undertaking if you are thinking about adding more than just a blog to your site.

The migrating from WordPress to Django process involved several challenges. It ultimately resulted in a successful migration with all content preserved and properly formatted. In this post, I'll share the approach, tools, and lessons learned during this migration journey.

I am assuming if you are reading this you already know what Django is and why it is so great. Otherwise you can read more about it here - What is Django?

Key takeaways
  • The migration is only worth undertaking if you are thinking about adding more than just a blog to your site.
  • I exported from WordPress, converted the XML to JSON and imported through custom Django management commands.
  • Importing in small batches of 5-10 posts made problems much easier to troubleshoot.
  • Draft posts, slugs, shortcodes, media and messy HTML were the main challenges.

Why Migrate from WordPress to Django?

Before diving into the how, let's briefly discuss why you might want to make this transition:

  • Greater development flexibility: Django gives you complete control over your codebase
  • Performance improvements: Django sites often load faster than WordPress installations
  • Security benefits: Fewer plugins means a reduced attack surface
  • Learning opportunity: Working with Python and Django enhances your skillset
  • Integration with other Python tools: Connect easily with data science libraries and more

The Migration Process Overview

The WordPress to Django migration followed these general steps:

  1. Exporting content from WordPressDownload the XML export file.
  2. Converting WordPress XML export to JSONJSON is easier to parse and import.
  3. Creating a Django data structure compatible with our modelsMake sure the models can hold the WordPress content.
  4. Developing custom management commandsImport, clean, validate and fix.
  5. Importing data in batchesSmall batches are easier to troubleshoot.
  6. Validating and cleaning the imported contentCheck URLs, templates and media.

Let's look at each of these steps in detail.

Step 1: Exporting WordPress Content

The migration begins with exporting your WordPress content. WordPress provides a built-in tool for this:

  • Log in to your WordPress admin dashboard
  • Navigate to Tools → Export
  • Choose "All content" to include posts, pages, comments, etc.
  • Download the XML file

This XML file contains all your posts, pages, media, categories, tags, and other content in WordPress's WXR (WordPress eXtended RSS) format.

Important

If you have content in DRAFT form or waiting to be published, these posts will not move over well!

Step 2: Converting WordPress XML to JSON

Working with XML can be cumbersome, so I converted the export file to JSON for easier processing:

Various online tools can perform this conversion - I used https://jsonformatter.org/xml-to-json

Alternatively, you can use Python libraries like xmltodict to convert XML to JSON

The resulting JSON file is more manageable for parsing and importing

This conversion step simplifies the data extraction process and makes it easier to map WordPress fields to Django model fields.

Step 3: Creating Django Data Structures

Before importing the data, I needed to ensure my Django models could accommodate the WordPress content structure. This involved:

Analysing the WordPress data schema (posts, categories, tags, etc.)

  • Creating or modifying Django models to match this structure
  • Setting up appropriate relationships between models

My Django blog application uses models for:

  • Posts (content, publication date, status)
  • Categories (name, slug)
  • Media (images and attachments)

Step 4: Developing Custom Management Commands

The heart of the migration process involved creating several Django management commands:

The Import Command

This command was responsible for:

  • Reading the JSON data
  • Parsing WordPress posts and categories
  • Creating corresponding Django objects
  • Handling media imports
  • Managing relationships between content

The Content Cleaning Command

WordPress content often contains HTML that doesn't translate well to Django templates. This command:

  • Removes unnecessary WordPress-specific HTML
  • Fixes formatting issues
  • Cleans up embedded media
  • Ensures content renders properly in Django templates

The Slug Validation Command

WordPress and Django handle URL slugs differently. This command:

  • Validates all post and category slugs
  • Identifies slugs that don't match Django's URL patterns
  • Reports problematic content that needs attention

The Slug Fixing Command

To address issues identified by the validation command, this tool:

  • Automatically regenerates invalid slugs from post titles
  • Ensures unique slugs across all content
  • Updates database records with corrected slugs

Step 5: Importing Data in Batches

Importing all content at once can be risky and resource-intensive. Instead, I used a batch processing approach:

  • Imported content in small batches (5-10 posts at a time)
  • Used offset parameters to control which content was imported
  • Added year/month filters to organize imports chronologically
  • Created a wrapper script to automate the batch process

This approach provided several benefits:

  • Easier to troubleshoot if issues arose
  • Reduced server load during imports
  • Allowed for pausing and resuming the import process
  • Provided better visibility into progress

Step 6: Validating and Cleaning Imported Content

After importing, several quality assurance steps ensured everything was working properly:

  • Running the validation command to check for URL resolution issues
  • Cleaning WordPress-specific HTML and formatting
  • Checking template rendering for all imported content
  • Verifying media and embedded content displayed correctly

Common Challenges and Solutions

During the migration, I encountered several challenges that required specific solutions:

Challenges and how I solved them
Challenge Problem Solution
Invalid Slug Formats WordPress sometimes uses query parameter formats in slugs (like ?p=123) that aren't compatible with Django's URL patterns. Created a custom management command that identifies these slugs and automatically regenerates them from post titles, ensuring they match Django's URL pattern requirements.
WordPress Shortcodes WordPress content often contains shortcodes (, , etc.) that don't work in Django. The content cleaning command identifies and processes these shortcodes, either converting them to standard HTML or removing them when appropriate.
Media Handling WordPress stores media in a specific directory structure that differs from Django's approach. Implemented media downloading and remapping to ensure all images and attachments were correctly imported and properly referenced in content.
Content Formatting WordPress adds various classes, inline styles, and non-semantic HTML that can cause rendering issues. Created a content cleaning process using BeautifulSoup that sanitizes HTML, removes unnecessary attributes, and improves semantic structure.
Draft Posts Some WordPress posts might be in draft status but still need to be imported. The import command preserves post status, ensuring draft posts remain unpublished in the Django site while still being imported.

Lessons Learned

This migration taught me several valuable lessons:

Before you migrate

Tick off each lesson as you read it

  • Start with a small test setImport a few representative posts first to identify potential issues before running the full import.
  • Validate early and oftenCreate validation tools from the beginning to catch issues as they arise.
  • Plan for content cleaningWordPress content almost always needs cleaning to work well in Django templates.
  • Batch processing is essentialBreaking the import into manageable chunks makes troubleshooting much easier.
  • Keep track of what's importedUse logging and tracking to know which content has been successfully imported.
  • Watch out for draft postsBe aware of post status and publication dates when importing.

Migrating from WordPress to Django is a complex but rewarding process. By breaking it down into methodical steps and creating custom tools to handle specific challenges, you can successfully transition your content while maintaining its integrity. The management commands created for this process can be reused for future content migrations, making them valuable additions to your Django toolkit. While the initial setup requires effort, the long-term benefits of having your content in a flexible, powerful framework like Django make the migration well worth it.

Your turn

Is a migration right for you?

  1. Are you thinking about adding more than just a blog to your site?The migration is only worth undertaking if you are.
  2. Do you have posts in draft form or waiting to be published?These will not move over well, so list them first.
  3. Which five posts would make a good small test set?
Summary
  • Export from WordPress, convert the XML to JSON, then import with custom management commands.
  • Import in small batches and validate as you go.
  • Expect to clean slugs, shortcodes, media and formatting.
  • The commands can be reused for future content migrations.
Keep reading

Django Project Structure

The consistent project structure I use across all of my Django projects.

Read more →

When To Use Headless CMS

When headless makes sense and when to stick with traditional WordPress.

Read more →

What I Learned Setting Up VPS Hosting with Hetzner and HestiaCP

How I moved my hosting from cpanel to a self-managed VPS.

Read more →