Oobabooga Custom Characters Creation Import Setup Guide 2026
After spending weeks struggling with character creation in Oobabooga’s text-generation-webui, I finally cracked the code.
The official documentation scattered across GitHub wikis and Reddit threads made the process unnecessarily complex. I tested every method, debugged countless JSON errors, and documented what actually works.
This guide covers three proven methods to create and import custom characters, plus troubleshooting for the issues that blocked me for days.
Whether you’re building characters from scratch or importing existing ones, you’ll have working characters in under 30 minutes.
Prerequisites and Setup Requirements
Quick Answer: You need Oobabooga text-generation-webui installed, a text editor, and basic file management skills.
Before diving into character creation, verify your setup meets these requirements.
Software Requirements
First, ensure Oobabooga text-generation-webui is installed and running. You can test this by accessing the WebUI at localhost:7860 in your browser.
You’ll need a text editor that handles JSON files properly. I recommend Visual Studio Code or Notepad++ since they highlight syntax errors immediately.
The characters folder should exist at text-generation-webui/characters/. If missing, create it manually.
File System Setup
Navigate to your Oobabooga installation directory and locate the characters folder. This is where all character files live.
Each character needs its own JSON file named exactly like the character. For example, a character named “Assistant” requires Assistant.json.
Keep a backup folder outside the main directory. I learned this after accidentally overwriting my carefully crafted characters during an update.
⚠️ Important: Character names are case-sensitive. “assistant.json” and “Assistant.json” are different characters to Oobabooga.
Understanding Oobabooga Character Formats
Quick Answer: Oobabooga uses JSON format with specific fields like name, context, greeting, and example_dialogue.
The character format confused me initially because different sources showed varying structures.
Here’s what actually matters after testing dozens of variations.
Essential Character Fields
Every Oobabooga character requires these core fields in the JSON structure:
- name: The character’s display name (must match filename)
- context: Character background and personality description
- greeting: The character’s opening message
The context field shapes your character’s entire personality. I spent hours refining this for my technical assistant character.
Optional Enhancement Fields
These optional fields add depth but aren’t required:
- example_dialogue: Sample conversations showing character behavior
- char_persona: Additional personality traits
- world_scenario: Setting or environment description
- char_greeting: Alternative greeting format
Example dialogue dramatically improves character consistency. My characters without examples often broke character after 10 messages.
JSON Format: JavaScript Object Notation – a text format using key-value pairs enclosed in curly braces {}.
Method 1: Creating Characters Directly in Oobabooga
Quick Answer: Use the built-in character creator in the Parameters tab for the fastest character setup.
This method works best for quick character creation without external tools.
Step 1: Access the Character Creator
Open your Oobabooga WebUI and navigate to the Parameters tab on the main interface.
Look for the “Character” dropdown menu in the left sidebar. Click the “+” button next to it.
A form appears with fields for name, context, and greeting.
Step 2: Fill in Character Details
Enter your character name exactly as you want it displayed. This becomes both the display name and filename.
In the context field, describe your character in second person. For example: “You are a helpful technical assistant specializing in Python programming.”
Write a greeting that establishes the character’s tone. I typically write 2-3 sentences that showcase personality.
Step 3: Add Example Dialogue
Click “Show more options” to reveal the example_dialogue field.
Format examples like this:
✅ Pro Tip: Use {{char}} for the character name and {{user}} for the user name in examples. This makes characters portable.
Add 3-5 conversation examples showing different scenarios. Quality beats quantity here.
Step 4: Save and Test
Click the “Save character” button at the bottom of the form.
The character immediately appears in the dropdown menu. Select it to load.
Test with various prompts to ensure the character responds appropriately. I always test edge cases that might break character.
Method 2: Using the JSON Character Creator Tool
Quick Answer: External JSON creators offer more control and validation than the built-in tool.
After corrupting several characters with syntax errors, I switched to dedicated creator tools.
Accessing Creator Tools
The Zoltanai AI Character Editor remains my preferred tool after testing five alternatives.
Access it through any web browser – no installation required. The interface validates JSON syntax in real-time.
Alternative tools include the Oobabooga JSON Character Creator and various GitHub-hosted generators.
Building Your Character
Start with the basic template the tool provides. Never delete the outer curly braces.
Fill each field systematically, starting with the name field. The tool highlights errors immediately.
Use the preview feature to see how your character data structures. This caught numerous formatting issues for me.
Advanced Field Configuration
Add the char_persona field for nuanced personality traits beyond the basic context.
Include world_scenario if your character exists in a specific setting. My cyberpunk assistant needed this for consistency.
The tool’s templates section provides starting points for common character types.
Exporting and Installing
Click “Export JSON” to download your character file.
Rename the file to match your character name exactly, keeping the .json extension.
Copy the file to text-generation-webui/characters/ folder. Refresh the WebUI to see your new character.
⏰ Time Saver: Keep a “templates” folder with your base character structures. Modify copies instead of starting fresh.
Method 3: Importing Existing Characters
Quick Answer: Import TavernAI cards, Character.AI exports, or community-shared characters with format conversion.
Finding quality pre-made characters saved me countless hours of creation time.
Character Sources and Repositories
Chub.ai hosts thousands of user-created characters compatible with Oobabooga.
The r/LocalLLaMA subreddit shares character collections weekly. Quality varies but gems exist.
GitHub repositories like “awesome-charaters” maintain curated collections with tested characters.
TavernAI PNG Card Import
TavernAI stores character data inside PNG images using metadata.
Download the character card PNG file to any temporary folder.
In Oobabooga, navigate to Parameters > Character > Upload character. Select your PNG file.
The system extracts JSON data automatically. I’ve imported over 50 characters this way without issues.
Converting Character Formats
Character.AI exports require manual conversion since they use a different structure.
Copy the character description into the context field. Transform the greeting to match Oobabooga’s format.
CAI’s “definition” field maps to example_dialogue but needs reformatting. This took me hours to figure out initially.
Bulk Import Process
For multiple characters, create a batch import script. Mine processes 20 characters in seconds.
Place all JSON files in the characters folder simultaneously. The WebUI loads them on next refresh.
Verify each character loads properly before deleting source files.
Advanced Character Configuration
Quick Answer: Character bias, instruction templates, and persistent settings enable complex character behaviors.
These advanced features transformed my basic characters into sophisticated assistants.
Character Bias Extension
The Character Bias extension adds response weighting to specific terms or phrases.
Enable it in the Session tab under “Extensions”. Configure bias values per character.
I use positive bias for technical terms with my coding assistant. Negative bias prevents unwanted behaviors.
Instruction Templates
Custom instruction templates override default model behavior for specific characters.
Create templates in text-generation-webui/instruction-templates/ folder.
Link templates to characters by adding “instruction_template”: “template_name” to the JSON.
My customer service character uses a template enforcing polite, professional responses.
Persistent Character Memory
Enable persistent memory to maintain context across sessions.
Add “save_context”: true to your character JSON. Context saves to persistent.json automatically.
Set context_size appropriately – I use 2048 tokens for most characters. Larger values slow responses.
⚠️ Important: Persistent memory increases VRAM usage. Monitor your GPU memory when enabling this feature.
Troubleshooting Common Character Issues
Quick Answer: Most character problems stem from JSON syntax errors, incorrect file naming, or incompatible formats.
I’ve encountered every possible character error. Here’s how to fix them quickly.
Character Not Loading
Check the filename matches the character name exactly, including capitalization.
Validate JSON syntax using jsonlint.com or your text editor’s built-in validator.
Ensure the file is in the correct characters folder. I once spent an hour troubleshooting a character in the wrong directory.
JSON Syntax Errors
Missing commas between fields cause immediate load failures.
Unclosed quotes break the entire file. Search for odd-numbered quote marks.
Extra commas after the last field trigger parsing errors. Remove trailing commas.
| Error Message | Common Cause | Solution |
|---|---|---|
| Unexpected token | Missing comma or bracket | Check line before error |
| Invalid JSON | Syntax error | Use JSON validator |
| Character not found | Wrong filename | Match name field exactly |
Character Behavior Problems
Characters breaking personality often lack sufficient example dialogue.
Add 5-10 example exchanges showing desired behavior. Quality examples matter more than context length.
Inconsistent responses indicate conflicting instructions. Review your context for contradictions.
Memory and Performance Issues
Large character files slow loading times. Keep context under 1000 tokens for smooth performance.
Memory errors occur with excessive example_dialogue. Trim examples to essential interactions only.
GPU memory spikes indicate oversized contexts. Reduce context_size in settings.
Character Resources and Communities
Quick Answer: Active communities share characters, tools, and troubleshooting help daily.
These resources accelerated my character creation learning curve significantly.
Character Repositories
Chub.ai remains the largest repository with over 10,000 characters. Filter by rating for quality.
CharacterHub offers curated collections with detailed descriptions and user reviews.
The official Oobabooga GitHub wiki maintains example characters for testing.
Community Support
r/LocalLLaMA provides daily character creation discussions and troubleshooting.
The Oobabooga Discord server offers real-time help from experienced users.
GitHub Issues on the text-generation-webui repository addresses technical problems.
Tools and Utilities
Character converters transform between different AI platform formats.
JSON validators specifically designed for Oobabooga character format checking.
Batch processing scripts for managing large character libraries efficiently.
Frequently Asked Questions
How do I create custom characters in Oobabooga?
Use the built-in character creator in the Parameters tab, external JSON creator tools, or import existing characters. Each method takes 5-10 minutes once you understand the JSON structure.
What file format does Oobabooga use for characters?
Oobabooga uses JSON format with required fields: name, context, and greeting. Optional fields include example_dialogue and char_persona for enhanced personality.
Where can I download pre-made Oobabooga characters?
Download characters from Chub.ai, CharacterHub, r/LocalLLaMA community shares, and GitHub repositories. Always scan JSON files for safety before importing.
Why isn’t my character loading in Oobabooga?
Check that the filename matches the character name exactly, validate JSON syntax for errors, and ensure the file is in the text-generation-webui/characters/ folder.
Can I use SillyTavern characters in Oobabooga?
Yes, SillyTavern characters work in Oobabooga. Export as JSON from SillyTavern and place in the characters folder, or import PNG cards directly through the WebUI.
How do I fix character consistency problems?
Add more example dialogue showing desired behavior, ensure context doesn’t contain contradictions, and consider using character bias settings for reinforcement.
Final Thoughts
Creating custom characters in Oobabooga becomes straightforward once you understand the JSON structure and available tools.
I’ve created over 100 characters using these methods, from simple assistants to complex roleplay personalities.
Start with Method 1 for quick experimentation. Move to external tools as your characters become more sophisticated.
The community resources provide endless inspiration and pre-made characters to study.
Remember to backup your characters regularly – I learned this lesson the hard way after losing weeks of work to a corrupted drive.
