How to Install a Custom Pet in OpenAI Codex (macOS & Windows)

2026-07-27

A complete step-by-step guide to installing your PetGen pixel-art companion in OpenAI Codex. Covers both macOS and Windows, with troubleshooting tips for beginners.

What you need before you start

Before installing a custom pet in Codex, make sure you have: (1) OpenAI Codex desktop app, (2) your pet package from PetGen (ZIP with spritesheet.webp and pet.json), and (3) a terminal or command prompt.

Your pet package is ready the moment you download it. No extra conversion is needed.

macOS installation

Extract the ZIP, open Terminal, run: mkdir -p ~/.codex/pets && cp -r ~/Downloads/my-pixel-pet ~/.codex/pets/

Restart Codex completely (Cmd+Q and relaunch). Your pet should appear.

Windows installation

Extract the ZIP, open PowerShell, run: Copy-Item -Recurse "$env:USERPROFILE\Downloads\my-pixel-pet" "$env:USERPROFILE\.codex\pets\"

Fully restart Codex. Your pet should appear and animate.

Troubleshooting

Pet not showing: Check folder structure matches pet.json naming
Blank square: Spritesheet missing or corrupt, re-download
Permission error on macOS: Add sudo before cp

Frequently asked questions

How do I install a custom pet in Codex?

Download the ZIP from PetGen, extract it, and copy the folder into ~/.codex/pets/ on macOS or %USERPROFILE%.codexpets on Windows. Then fully restart Codex (Cmd+Q on macOS, close and reopen on Windows). Your pet should appear on your desktop.

Why is my Codex pet not showing after installation?

The most common cause is a folder name mismatch. The folder name in ~/.codex/pets/ must exactly match the "name" field in pet.json. Check that your folder is named correctly and restart Codex completely.

Does Codex pet installation affect my OpenAI model?

No. Codex pets are purely cosmetic desktop companions. They do not modify your coding model, change your prompts, or affect your API usage in any way. Your Codex AI remains exactly the same.

Can I install multiple pets in Codex?

Yes! You can have multiple pets by creating separate folders in ~/.codex/pets/. Each folder should contain its own spritesheet.webp and pet.json. Codex will display them as selectable companions.

Share this article:

Try it yourself

Ready to turn your own photo into a pixel-art pet? Upload it on PetGen and get your spritesheet + pet.json in minutes.

Generate your pet now →

← Back to blog