Palworld save tools: convert legacy saves to JSON safely

Palworld save tools from cheahjs converts compatible legacy saves to JSON and back, but its original release cannot read saves from Palworld 0.6 onward. If your world comes from the current 1.0 game, stop before using these commands on it. This guide explains the older converter, how to preserve separate input and output files, and what conversion can actually tell you. We checked the author documentation and installed version 0.24.0 to verify its command help; we did not convert or restore a real game save. The 20-minute estimate covers preparation, not guaranteed processing or recovery time.

Choose Palworld save tools for the right version#

Check the save’s originating game version before installing a converter. The original project’s 0.24.0 release explicitly says that 0.6 saves are no longer readable. An old tutorial’s successful example does not establish support for a newer world.

The package on PyPI is version 0.24.0, uploaded October 6, 2024, and requires Python 3.9 or newer. Those facts identify the software in this guide. They do not make every save created before 0.6 compatible: the same release notes describe temporarily disabled item-slot decoding following a 0.3.7 change. Check the exact file and operation, not just whether its date looks old enough.

The PST author’s notice marks that separate toolkit discontinued. Installing a similarly named package does not give you its features or a successor’s compatibility fixes.

For a current world, start with the save-editor guide and its tool limitations. Continue below only for an appropriately supported legacy file. Record the converter version alongside the source game’s version so the resulting JSON remains traceable.

Preserve the world before making a working copy#

Work on a copy outside the live save directory. A converter’s output file is not a complete world backup, and copying only the largest file can omit data you will need later.

Use the Palworld save-file location reference to identify the authoritative world. A guest’s local files are not the dedicated server’s world. On a rented server, download a consistent copy through the provider’s supported file-access method after confirming the server has stopped.

1. Finish play and stop writes

   For a dedicated server, authenticate as administrator and use the documented chat commands:

   /Save
   /Shutdown 60 Maintenance

   Pocketpair’s command reference documents these operations. Confirm that the server process actually exits and that a service manager does not immediately restart it. For local co-op, exit the session normally before copying.

2. Keep a complete original separately

   Preserve the complete selected world directory, its player files, and relevant server configuration. Record the world identifier and game version. Keep this dated copy outside the working directory and away from any automatic cleanup or overwrite operation.

3. Create a disposable conversion folder

   Make another copy for inspection. Run the commands below from a folder containing that working copy of the save. Keep output names distinct so you can tell the input, exported JSON, and reconstructed candidate apart.

Do not rename a Game Pass container blob to make it look like a normal SAV file. Container extraction is a separate operation. Likewise, these Python commands do not provide an Xbox or PS5 console export interface. Your checkpoint is a known, compatible input plus an untouched backup you can locate without opening the converter.

Install the pinned converter in an isolated Python environment#

Use the same Python interpreter for installation and conversion. A virtual environment keeps this older package separate from other Python tools and makes the version you are running easier to confirm. The commands below assume you have already installed Python 3.9 or newer.

On Windows, open PowerShell in your disposable working directory:

py -3 --version
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install palworld-save-tools==0.24.0
.\.venv\Scripts\python.exe -m pip show palworld-save-tools
.\.venv\Scripts\python.exe -m palworld_save_tools.commands.convert --help

The Python version output must meet the requirement, and the package information must show 0.24.0. Calling the environment’s executable directly avoids requiring a PowerShell activation-policy change. If the Python launcher is missing, resolve your Python installation before proceeding; a missing command is not a save-file problem.

On Linux, use an available compatible Python 3 installation:

python3 --version
python3 -m venv .venv
.venv/bin/python -m pip install palworld-save-tools==0.24.0
.venv/bin/python -m pip show palworld-save-tools
.venv/bin/python -m palworld_save_tools.commands.convert --help

If your distribution reports that virtual-environment support is unavailable, install that support through its normal package-management instructions. Do not substitute an unrelated system-wide package or run conversion as an administrator merely to bypass setup errors.

The tagged packaging metadata establishes the package and console entry point. This guide uses the module form so the interpreter is explicit. Successful installation and help output verify the CLI is available; they do not test whether your world can be decoded.

Convert a compatible SAV into readable JSON#

For a supported working copy, provide an explicit output filename. In the Windows environment created above, run:

.\.venv\Scripts\python.exe -m palworld_save_tools.commands.convert "Level.sav" --output "Level.sav.json"

On Linux, the equivalent command is:

.venv/bin/python -m palworld_save_tools.commands.convert "Level.sav" --output "Level.sav.json"

The expected output is a new JSON file in the working directory. The input remains separate. Check the terminal for errors and confirm the output was written before opening it in an editor. A partially written file from a failed process is not a completed export.

The version 0.24.0 converter source shows that omitting the output option normally appends the JSON extension for this direction. Naming it explicitly makes the intended destination visible before you press Enter.

For less whitespace, use a different destination with the minification flag:

.\.venv\Scripts\python.exe -m palworld_save_tools.commands.convert "Level.sav" --output "Level.min.json" --minify-json

On Linux, replace the interpreter path with the Linux path shown above. Minification changes formatting, not the tool’s supported save versions. It also does not turn the converter into a streaming reader with a fixed memory limit.

Keep the default property selection for this introductory workflow. The release has decoding limitations, and requesting additional custom properties is not a general fix. If a supported-looking file raises an error, preserve the error and provenance first; do not infer that the world is corrupt merely because this parser rejected it.

Convert JSON back without replacing the original#

Use a new SAV filename for the reverse operation. Without an explicit output path, this converter removes the JSON extension, which can point straight back at your original file.

For Windows:

.\.venv\Scripts\python.exe -m palworld_save_tools.commands.convert "Level.sav.json" --output "Level.roundtrip.sav"

For Linux:

.venv/bin/python -m palworld_save_tools.commands.convert "Level.sav.json" --output "Level.roundtrip.sav"

This creates a candidate file for further checks. Keep all three artifacts: the input, the JSON, and the reconstructed SAV. The candidate’s distinct name is deliberate; it is not an instruction to place an extra world file into the live server directory.

First evaluate an unchanged export and reconstruction before considering any edit. Otherwise, an error has two possible causes immediately: the conversion itself and the change you introduced. Even an unchanged reconstruction that parses successfully still needs separate game-level validation before any restore.

Inspect identifiers without turning conversion into repair#

The JSON can expose supported world records for inspection, but the converter is not a set of character-repair commands. Its README describes structures such as the character map, group map, and base data:

CharacterSaveParameterMap
GroupSaveDataMap
BaseCampSaveData

Use those names as orientation within a successfully decoded legacy file, not as a universal schema for every game release. Fields can vary, and disabled decoding can leave data unsuitable for the edit you had in mind.

Keep your initial pass read-only. Write down what you found, including the record and identifier, instead of immediately changing it. Host migration, player removal, and restoration each require their own compatible procedure and checks; this guide does not supply those operations.

If “tools” meant additional behavior while the server runs, use the server-mods overview to distinguish that route. Offline JSON conversion and a running server mod have different purposes and compatibility requirements.

Handle large files and reject unsupported output#

Plan for both expanded JSON and the memory used during decoding. The original README warns about large output, while the converter source reads the save, decompresses it, and constructs objects before writing JSON. The compressed input’s size is therefore not a useful promise about peak memory use.

Prefer a separate computer with enough resources over competing with a live game server. Monitor actual memory and free disk space during a compatible conversion. There is no measured RAM formula, expansion ratio, or completion-time estimate from our checks that would justify promising a specific machine is sufficient.

Keep failed output clearly labeled so it cannot be mistaken for a restore candidate. If a large text editor freezes, that alone does not diagnose the underlying save; it may simply be unable to handle the exported document comfortably. Stop and preserve the original rather than repeatedly editing or truncating the JSON to make it open.

Validate a candidate world before any restore#

A conversion result is evidence about the converter, not proof that the game can load and preserve the world. If restoration is your goal, use a separate environment compatible with the source save and the intended operation. Never use the group’s only live world as that experiment.

Keep the reconstructed candidate distinct until a documented test workflow tells you where it belongs. Check that expected characters, inventories, Pals, guild membership, and base ownership appear. Include an unaffected character or record as a comparison. Then save, stop cleanly, restart, and repeat the relevant checks. A change visible once can still fail to persist or damage a relationship elsewhere.

These are acceptance checks for you to perform, not results we obtained. Our verification covered installation, command help, and source behavior. It did not establish lossless round-trip fidelity for any particular save, current-game compatibility, or a successful in-game restore.

Keep both conversion directions within a compatible tool and format. Do not assume another editor can consume this legacy JSON because its own interface also mentions JSON; the save-editor guide explains why newer tooling can differ. Record the exact versions and every warning with your candidate.

If any required check fails, retain the complete original and reject that candidate. If players have progressed since you took the copy, an old candidate also represents an older world state. Resolve that difference before contemplating replacement. Finishing this guide with a readable legacy export and an untouched original is a useful outcome even when restoration is not supported.