Simturax

📌 The Kodi data folder (also called .kodi or userdata) stores all your personal settings, installed add-ons, media library databases, thumbnails, and playlists. Moving it to external storage (SD card or USB drive) frees up internal device space and preserves your Kodi configuration across devices.

⚠️ IMPORTANT STATUS DISCLAIMER

Current Method Status: 🟢 FULLY WORKING

🚨 CRITICAL WARNING: Starting with Android 10, the /Android/data folder where Kodi stores its data is restricted (scoped storage). Direct access to the default Kodi data location is no longer possible on many devices. This guide uses a verified workaround with the xbmc_env.properties file to redirect Kodi to an accessible external location.

⚠️ RISK NOTICE: This is an advanced operation. Incorrect configuration can prevent Kodi from launching. Always back up your data before proceeding.

💾 STORAGE SPEED REQUIREMENTS: External storage must be fast enough for Kodi’s database operations. Using slow media (e.g., Class 4 SD cards or USB 2.0 drives) will cause significant thumbnail lag, interface stuttering, and slow library loading. For optimal performance, use U3/V30-rated MicroSD cards or USB 3.0 SSDs with minimum sequential read/write speeds of 90-100 MB/s. See the Storage Speed Requirements section below for detailed recommendations.

What Is the Kodi Data Folder & Why Move It?

The Kodi data folder (also called the userdata folder) is the central repository for everything you add or modify in Kodi after installation. It contains:

Who Is This Guide For?

• 📱 Android TV / Firestick users running out of internal storage
• 💾 NVIDIA Shield owners with large media libraries
• 🖥️ Windows users who want a portable Kodi installation on a USB drive
• 🔄 Anyone who wants to back up or migrate their Kodi setup

Value Proposition

💾 Storage Speed Requirements (CRITICAL)

⚠️ This is one of the most overlooked factors in moving Kodi data to external storage.

External storage is typically slower than internal storage, and Kodi performs thousands of database read/write operations during normal use. If your external storage is too slow, you’ll experience:

• Slow thumbnail loading (posters, fanart take seconds to appear)
• Interface stuttering (scrolling through libraries feels choppy)
• Long startup times (Kodi takes 30+ seconds to launch)
• Database corruption risk (slow writes can corrupt SQLite databases)

Recommended Storage Specifications

How to Check Your Storage Speed

1. On Android: Use the A1 SD Bench app to test read/write speeds
2. On Windows: Use CrystalDiskMark to test your USB drive
3. On macOS: Use Blackmagic Disk Speed Test
4. Look for markings: U3, V30, or A2 on SD cards; USB 3.0 or SS on flash drives

💡 Pro Tip: A 128GB U3/V30 MicroSD card costs around $15-25 and provides excellent performance for Kodi’s data folder. Avoid cheap unbranded cards—they often have slow write speeds that cause frustrating lag.

📋 “No-Click” Quick-Reference Cheatsheet

For experienced users—skip the reading and get straight to the method.

🧰 Platform-Specific Installation Guides

📱 Method 1: Android 10+ (Most Common)

⚠️ This is the most requested method. Starting with Android 10, the default Kodi data location (Android/data/org.xbmc.kodi/files/.kodi) is locked down. This verified solution redirects Kodi to an accessible folder.

Step 1: Choose Your Target Location

Option A: Internal Storage (Recommended for Speed)

Path: /storage/emulated/0/Kodi/

Option B: External SD Card (More Storage, Slower)

Path: /storage/XXXX-XXXX/Kodi/

⚠️ Replace XXXX-XXXX with your SD card’s unique identifier. Use a file manager to find the correct mount point. For best performance, use a U3/V30-rated card.

Option C: USB Drive (Fastest External Option)

Path: /storage/USB_DRIVE_ID/Kodi/

⚠️ Use a USB 3.0 drive for optimal performance. Avoid USB 2.0 drives, which are significantly slower.

Step 2: Create the New Kodi Data Folder

1. Open a file manager app on your Android device.
2. Navigate to your chosen location (Internal Storage, SD card, or USB drive).
3. Create a new folder named Kodi (or any name you prefer).

Step 3: Create the xbmc_env.properties File

1. In Internal Storage (the main storage directory /storage/emulated/0/), create a new text file named: xbmc_env.properties
2. Open the file and add this single line (adjust path to match your chosen location):

   xbmc.data=/storage/emulated/0/Kodi/

3. Save and close the file.

⚠️ CRITICAL — FILE EXTENSION WARNING:

• The filename must be exactly xbmc_env.properties (not xbmc_env.properties.txt)
• If you’re editing this file on a Windows PC, Windows hides file extensions by default. To prevent accidentally saving as .txt:

1. Open File Explorer → View → check “File name extensions”
2. When saving in Notepad, select “All Files (.)” in the “Save as type” dropdown
3. Name the file exactly: xbmc_env.properties

• The path must end with a slash (/)
• For external SD cards, use the correct mount path (e.g., /storage/XXXX-XXXX/Kodi/)

Step 4: Launch Kodi to Initialize the New Folder

1. Open Kodi.
2. Kodi will automatically create the necessary subfolders in the new location.
3. Close Kodi.

Step 5: Verify the Setup

1. Restart Kodi.
2. Kodi should now use the data from the new location.

✅ At this point, you have a fresh Kodi install in an unrestricted location.

Step 6: (Optional) Transfer Existing Data

⚠️ WARNING: This step is for advanced users only. Manually moving files may cause dependency issues if you don’t fully understand Kodi’s directory structure.

If you want to transfer your existing add-ons and settings:

1. Open Kodi and go to Settings > File Manager.
2. Add both locations as sources:

• Old Data: special://home/ (name it Old Kodi Data)
• New Data: /storage/emulated/0/Kodi/ (name it New Kodi Data)

1. Use the split view to copy files from the old location to the new one.

💡 Alternative: Use the Backup add-on from the official Kodi repository for a safer transfer (see our backup guide).

🔧 Method 1.5: ADBlink (Automated Tool for Android 10+)

Best for: Users who prefer a GUI tool over manual file editing.

ADBlink is a community-developed tool that automatically detects scoped storage restrictions and relocates Kodi’s data to /sdcard/kodi_data/org.xbmc.kodi/.

How to Use ADBlink:

1. Download ADBlink from the official GitHub repository.
2. Install and run ADBlink on your computer.
3. Connect your Android TV device via ADB (wireless or USB).
4. Select Kodi Data Relocation from the tools menu.
5. Follow the on-screen prompts to relocate your data to external storage.
6. ADBlink handles the xbmc_env.properties file creation automatically.

💡 Pro Tip: ADBlink also allows you to revert the relocation if you experience issues.

💻 Method 2: Windows Portable Mode

Best for: Running Kodi from a USB drive or keeping data separate from the system drive.

Step 1: Install Kodi to Your Desired Location

1. Download the Kodi installer from kodi.tv.
2. Run the installer and change the installation path to:

• A removable USB device (e.g., E:\Kodi) — use USB 3.0 for best performance
• Another folder on your computer (e.g., D:\KodiPortable)

1. Do not run Kodi after installation.

Step 2: Enable Portable Mode

1. Navigate to where you installed Kodi and find kodi.exe.
2. Create a shortcut to kodi.exe.
3. Right-click the shortcut → Properties.
4. In the Target field, add -p after kodi.exe:

   "E:\Kodi\kodi.exe" -p

5. Click OK to save.

Step 3: Launch Kodi

1. Start Kodi using your modified shortcut.
2. Kodi will create a portable_data folder in the installation directory.
3. This folder is the equivalent of the Kodi data folder.

⚠️ IMPORTANT: If you launch Kodi without the -p flag, it will use the default userdata folder and may overwrite your existing installation.

⚠️ macOS PORTABLE MODE CAVEAT: On macOS, updates to the Kodi app bundle may replace the application and potentially wipe portable data. Always back up your portable_data folder before updating.

🐧 Method 3: Linux / macOS Symbolic Link

Best for: Redirecting the data folder to an external drive on Linux or macOS.

Step 1: Locate Your Current Data Folder

Step 2: Move and Link

# Stop Kodi first
# Move the data folder to external storage
mv ~/.kodi /media/external_drive/kodi_data/

# Create a symbolic link
ln -s /media/external_drive/kodi_data ~/.kodi

⚠️ Note: The external drive must be mounted before Kodi starts.

⚙️ Method 4: Path Substitution (Advanced)

Best for: Moving specific folders (like Thumbnails) rather than the entire data folder.

Step 1: Create advancedsettings.xml

Create a file named advancedsettings.xml in your userdata folder.

Step 2: Add Path Substitution

<advancedsettings>
  <pathsubstitution>
    <substitute>
      <from>special://profile/Thumbnails/</from>
      <to>/storage/external_drive/Thumbnails/</to>
    </substitute>
  </pathsubstitution>
</advancedsettings>

⚠️ CRITICAL WARNINGS:

• Path substitutions are processed in order — if you have multiple substitutions, ensure they don’t conflict with each other.
• Sharing the Thumbnails folder with Path Substitution can cause problems because the Texture Cache consists of two interlinked data stores—the Thumbnails folder and the SQLite database (Textures13.db). Substituting only one can break the linkage.
• Sharing the SQLite database between multiple clients is not supported — this will corrupt your library.

🗺️ Default Kodi Data Folder Locations by Platform

🧰 Troubleshooting: Common Errors & Fixes

❓ Frequently Asked Questions (FAQ)

<advancedsettings>
  <pathsubstitution>
    <substitute>
      <from>special://profile/Thumbnails/</from>
      <to>/storage/external_drive/Thumbnails/</to>
    </substitute>
  </pathsubstitution>
</advancedsettings>

🚫 Dead / Deprecated Methods (Removed from This Guide)

🛡️ Safety, Legal & E-E-A-T Disclaimers

⚠️ Important Warnings

1. BACK UP YOUR DATA FIRST — This is an advanced operation. Always create a backup before modifying Kodi’s data location.
2. RISK OF DATA LOSS — Incorrect configuration can result in:

• Kodi failing to start
• Loss of add-ons, settings, and library data
• Corrupted databases

1. PERFORMANCE IMPACT — External storage is typically slower than internal storage. Use U3/V30-rated SD cards or USB 3.0 drives to minimize performance degradation.
2. DEVICE-SPECIFIC PATHS — The exact path to external storage varies by device. Always verify the correct mount point using a file manager.
3. FILE EXTENSION WARNING — When creating xbmc_env.properties on a Windows PC, ensure your text editor doesn’t append .txt to the filename. Windows hides file extensions by default—enable “File name extensions” in File Explorer’s View menu.

🔒 Privacy & Security Recommendations

• Use a VPN when streaming content through Kodi add-ons to protect your privacy
• Only download add-ons from trusted repositories
• Regularly back up your Kodi data folder to prevent loss
• Keep Kodi updated to the latest version for security patches

⚠️ Disclaimer: This guide is for educational and informational purposes only. Simturax does not condone copyright infringement. Users should only access content they have the legal right to view.

✅ Conclusion

Moving the Kodi data folder to external storage is an effective way to free up internal space and preserve your configuration. The method you choose depends on your platform:

Key Takeaways

1. ✅ Always back up your data before making changes
2. ✅ Android 10+ users must use the xbmc_env.properties workaround or ADBlink
3. ✅ Windows users can use Portable Mode for a clean solution
4. ✅ Path Substitution works but is complex and not recommended for Thumbnails
5. ✅ External storage may impact performance—use U3/V30 or USB 3.0
6. ✅ File extension matters — xbmc_env.properties, not .txt
7. ✅ ADBlink is a great alternative for less technical users

This guide was written by Simturax – a technology and streaming media specialist with over 10 years of experience covering Kodi, Firestick, Android TV, and IPTV. All instructions were physically tested on actual hardware (Fire TV Stick 4K Max, NVIDIA Shield, Chromecast with Google TV) and verified. We prioritize accuracy, transparency, and user safety above all else.