Skip to main content

​
Quickstart Guide

This guide will walk you through downloading and processing your first DAT files with Datoso. By the end, you’ll have successfully fetched ROM metadata and organized it for use with your emulators.

​
Prerequisites

Before starting, make sure you have:
  • Installed Datoso with at least one seed plugin (see Installation)
  • Python 3.11 or higher
  • An active internet connection for downloading DAT files

​
Your First DAT Workflow

1

Check your installation

First, verify that Datoso is installed and see which seeds are available:
datoso --version
datoso seed installed
You should see the version number and a list of installed seed plugins. If you haven’t installed any seeds yet, go back to the Installation guide.
2

Download DAT files

Let’s fetch DAT files from a preservation source. We’ll use Redump as an example:
datoso redump --fetch
This command downloads all available DAT files from Redump. The fetch process may take several minutes depending on the source and your connection speed.
You can also use --fetch with other seeds like nointro, fbneo, or pleasuredome. Replace redump with your preferred seed name.
Be cautious with DAT-o-MATIC sources: Some sources like No-Intro (via DAT-o-MATIC) may have CAPTCHA protection. Excessive automated requests could result in temporary bans.
3

Process the DAT files

After fetching, process the DAT files to organize them into your preferred structure:
datoso redump --process
Processing parses the DAT files, applies your configuration rules, and reorganizes the metadata into an emulator-friendly folder structure.
4

Filter by system (optional)

If you only want to process specific systems, use the --filter flag:
datoso redump --process --filter "Sony - PlayStation"
The filter performs a partial name match, so --filter IBM would match “IBM - PC compatible” and “IBM PC”.
5

Verify the results

Check which DATs have been processed:
datoso dat --all
This shows all DATs in your local database with their current status.

​
Common Workflows

​
Fetch and Process in Sequence

You can chain fetch and process operations together: 
# Fetch and immediately process all DATs
datoso nointro --fetch
datoso nointro --process

# Or fetch multiple seeds, then process them all
datoso nointro --fetch
datoso redump --fetch
datoso nointro --process
datoso redump --process

​
Update All Seeds

To update all installed seeds at once, use the all command: 
# Fetch all seeds
datoso all --fetch

# Process all seeds
datoso all --process
Using datoso all --fetch will attempt to download from all installed seed sources. This can take a significant amount of time and bandwidth.

​
Process with Filters

Filter by partial name matches to process only specific systems: 
datoso nointro --process --filter Nintendo

​
Overwrite Existing DATs

By default, Datoso won’t overwrite existing processed DATs. To force reprocessing: 
datoso redump --process --overwrite

​
Working with DAT Metadata

​
View DAT Details

To see information about a specific DAT: 
# Search for a DAT by name
datoso dat --dat-name "PlayStation"

# Search within a specific seed
datoso dat --dat-name "redump:PlayStation"

​
Show Specific Fields

Display only the fields you’re interested in: 
datoso dat --dat-name "redump:psx" --fields name system date path
Available fields include: name, modifier, company, system, seed, date, path, system_type, full_name, automerge, parent, version, prefix, suffix, status, new_file, file, mias, static_path.

​
Set DAT Properties

Modify properties of a specific DAT: 
# Set a property
datoso dat --dat-name "redump:psx" --set automerge=true

# Unset a property
datoso dat --dat-name "redump:psx" --unset automerge

​
Deduplication

Remove duplicate ROM entries between parent and child DAT files: 
# Basic deduplication
datoso deduper --input "redump:psx_demos" --parent "redump:psx"

# Specify output file
datoso deduper --input "redump:psx_demos" --parent "redump:psx" --output "/path/to/deduped.dat"

# Auto-merge mode (uses database parent relationships)
datoso deduper --input "redump:psx_demos" --auto-merge
The dedupe command removes any ROM entries in the input DAT that already exist in the parent DAT, helping eliminate redundancy in your collection.

​
Health Check

Run the doctor command to verify your Datoso installation and identify any issues: 
# Check all installed seeds
datoso doctor

# Check a specific seed
datoso doctor redump

# Attempt automatic repairs
datoso doctor --repair
The doctor command validates:
  • Seed installation integrity
  • Required dependencies
  • Configuration files
  • Database connectivity

​
Configuration

​
View Current Configuration

# Display all configuration settings
datoso config

# Get a specific setting
datoso config --get PATHS.DatPath

​
Modify Configuration

# Set a configuration option (global)
datoso config --set PROCESS.Overwrite true

# Set a configuration option (local project)
datoso config --set PROCESS.Overwrite true --local

# Save current configuration to file
datoso config --save
Configuration is stored in:
  • Global: ~/.config/datoso/datoso.config (Linux/macOS)
  • Local: .datosorc in your current directory

​
Troubleshooting

​
Enable Verbose Output

For detailed logging and debugging information: 
datoso redump --fetch --verbose

​
View Logs

Check the application log for errors: 
datoso log

​
Common Issues

If you see “No seeds installed” or commands don’t work, install at least one seed:
pip install datoso[nointro]
Some sources (especially DAT-o-MATIC) may have CAPTCHA protection. If you encounter this:
  • Wait before retrying
  • Avoid running --fetch too frequently
  • Consider manual DAT downloads if automated fetching is blocked
If you encounter permission errors, ensure:
  • You have write access to ~/.config/datoso/
  • The configured DAT output paths are writable
  • You’re running Datoso with appropriate permissions

​
Next Steps

Now that you’ve completed your first DAT workflow, explore these topics:

Core Concepts

Learn about seeds, DATs, and how Datoso organizes ROM metadata

Commands Reference

Explore all available commands and their options

Configuration

Customize paths, rules, and processing behavior

Guides

Step-by-step guides for common workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us