CLEO is a library for GTA San Andreas that lets the game load custom scripts from a CLEO folder. To install it, you put the CLEO files and an ASI loader into your game directory, drop .cs scripts into the CLEO folder, and launch. The details depend on your game version, so check that first. That single step decides whether everything else works.
Install steps
- Confirm your gta_sa.exe version.
- Back up your game folder.
- Install an ASI loader.
- Copy CLEO 5 into the game folder.
- Add .cs scripts to the CLEO folder.
- Launch and check the main menu.
What CLEO actually does
San Andreas runs its missions and world logic from compiled script code. CLEO hooks into that system and adds new commands (opcodes), so modders can write small standalone scripts that run alongside the main game.
That covers a huge chunk of SA modding: new player abilities, vehicle features, HUD tweaks, camera changes and gameplay overhauls. Most “CLEO mods” are single .cs files under 50 KB. The library is just the engine that runs them.
The history matters because you will meet scripts written for every era:
- CLEO 1 to 3 were created by Seemann, who also makes the Sanny Builder script editor.
- CLEO 4 was developed by Alien and Deji and became the standard for over a decade. Its last widely used release was 4.4.4.
- CLEO 5 is the current branch, maintained on GitHub under the cleolibrary organisation. It focuses on stability, better error reporting and keeping compatibility with older scripts.
- CLEO Redux, also by Seemann, is a separate project. It runs JavaScript and classic scripts and supports the Definitive Edition, which regular CLEO does not.
For a fresh install on the classic PC game, use CLEO 5. Only stay on CLEO 4 if a specific script you care about refuses to run under 5.
Requirements at a glance
| Requirement | Details |
|---|---|
| Game | GTA San Andreas classic PC, not the Definitive Edition |
| Executable | v1.0 US gta_sa.exe (the version most mods target) |
| ASI loader | Ultimate ASI Loader by ThirteenAG or Silent’s ASI Loader |
| CLEO build | CLEO 5 from the cleolibrary GitHub releases page |
| Optional | SilentPatch by Silent, Modloader by LINK/2012 |
| Editor (for writing scripts) | Sanny Builder by Seemann |
Before you install
CLEO scripts can write data into your save files. Start a new save or back up your existing ones in Documents\GTA San Andreas User Files before you add anything.
Step 1: Confirm your game version
This is where most failed installs come from. CLEO and almost every ASI mod for San Andreas are built for the original v1.0 US executable. Copies bought later on Steam or through the Rockstar Games Launcher ship with newer executables, and CLEO 5 will not load against those.
A quick way to check is the file size of gta_sa.exe in your game folder. The 1.0 US executable is about 14.3 MB. The Steam 3.0 build and the Rockstar Launcher build are different sizes and also behave differently (missing radio tracks, changed save locations). If the size doesn’t match, your copy needs to be downgraded.
The SA modding community has downgrade patchers that convert your own legitimately bought Steam or Rockstar Launcher install back to 1.0 US. You’ll find them discussed on GTAForums and MixMods. Run the patcher on your own copy. Don’t download a random pre-made gta_sa.exe from a file host; those are often cracked executables, and some carry malware.
A note on availability: Rockstar delisted the classic PC versions in October 2021, about a month before the Definitive Edition launched, and later brought them back to the Rockstar Store as a bundle. If you only own the Definitive Edition, regular CLEO is not for you. CLEO Redux is the project to look at, and its scripts are a separate ecosystem.
Step 2: Back up your game folder
Copy the entire San Andreas folder somewhere safe before you add any mods. A clean 1.0 US backup is the most useful thing you can keep. When a mod setup goes wrong, you restore it in a minute instead of reinstalling and downgrading again.
Back up the user files too. On Windows those live in Documents\GTA San Andreas User Files, which holds your GTASAsf save slots and settings.
Step 3: Install an ASI loader
CLEO 5 ships as cleo.asi, which is a plugin, not something the game loads by itself. An ASI loader makes the game load any .asi file it finds in the game folder (and, depending on the loader, in a scripts folder).
Two loaders are standard:
- Ultimate ASI Loader by ThirteenAG. You place its DLL in the game folder under a name the game already loads. For San Andreas, the usual choice is
vorbisFile.dll, after renaming the original tovorbisHooked.dll, as the loader’s readme describes. - Silent’s ASI Loader by Silent, which uses the same
vorbisFile.dllapproach and is the one many SA mod packs bundle.
Pick one. Two ASI loaders fighting over the same DLL slot is a classic cause of crashes on startup. If you already run SilentPatch or other .asi mods that work, you already have a loader and can skip this step.
Modder's note
CLEO 4’s installer used to swap vorbisFile.dll itself. If you are upgrading from CLEO 4 to 5, check that you still have a real ASI loader in that slot and not a leftover CLEO 4 file, or cleo.asi will silently never load.
Step 4: Copy CLEO 5 into the game folder
Download the latest CLEO 5 release archive from the cleolibrary GitHub repository. Open the release notes before extracting, because the CLEO team lists exactly which files go where and any version-specific changes there.
The layout you end up with in the game root looks roughly like this:
| File or folder | What it is |
|---|---|
cleo.asi |
The CLEO library itself |
cleo\ |
Where your scripts go |
cleo\cleo_plugins\ |
Plugins (.cleo files) that add extra opcodes |
cleo\cleo_text\ |
Custom text (.fxt files) used by scripts |
cleo\cleo_saves\ |
Script save data CLEO writes itself |
Extract the archive straight into the folder containing gta_sa.exe, and say yes to merging folders. Don’t nest it one level deeper by accident (for example GTA San Andreas\CLEO5\cleo.asi). The game won’t see it there.
Uninstalling CLEO 4 first
If you have CLEO 4 installed, remove its files before adding CLEO 5: the old cleo.asi, the CLEO 4 versions of plugins and anything the CLEO 4 installer replaced. Keep your scripts in a separate folder so you can test them under CLEO 5 one at a time. Mixing library versions is how you get crashes nobody can diagnose.
Step 5: Add scripts to the CLEO folder
A CLEO script is a compiled file you drop into cleo\. That’s the whole install for most of them. The extension tells you how it runs:
| Extension | Meaning |
|---|---|
.cs |
Custom script. Starts automatically when you load a game and runs in the background |
.cm |
Custom mission. Doesn’t start on its own; another script or command launches it |
.cs3 |
Script that runs in CLEO 3 compatibility mode |
.cs4 |
Script that runs in CLEO 4 compatibility mode |
.fxt |
Text file for script messages; goes in cleo_text |
.cleo |
Plugin that adds opcodes; goes in cleo_plugins |
Read the readme that comes with each script. Plenty of scripts need a specific plugin, such as DK22Pac’s NewOpcodes or an INI and file-handling plugin. Others need a model or texture pack, an .fxt text file or an extra .ini for settings. If the readme says the script needs a plugin you don’t have, the script will either do nothing or throw an error at launch.
Download scripts from the long-running SA mod hubs: MixMods (run by Junior_Djjr, one of the most prolific SA script authors), LibertyCity, GTAinside and the GTAForums modding boards. Scan anything you download. Scripts are compiled code, and a .cs file can do anything the game can do, including messing up your save.
Keeping scripts organised with Modloader
Once you have more than a handful of mods, consider Modloader by LINK/2012. It lets you put each mod in its own subfolder inside modloader\ instead of overwriting game files. CLEO scripts placed inside a Modloader subfolder are picked up and loaded, so you can disable one by moving its folder or prefixing the name, without hunting through cleo\.
San Andreas has no equivalent of Vortex or MO2. If you’re coming from games where a multi mod manager handles deployment and profiles, Modloader is the closest thing SA has, and it’s worth setting up before your folder turns into a mess.
Step 6: Launch and confirm CLEO loaded
Start the game. On the main menu, CLEO shows its version number in a corner of the screen. If you see it, the library loaded. If you don’t, the ASI loader isn’t working or cleo.asi is in the wrong place.
Then load a save (or start a new game) and test what your script is supposed to do. Most .cs scripts are triggered by a key, a key combination or a typed cheat-style string, and the readme lists which. Nothing happening usually means you’re pressing the wrong key, not that the install failed.
Test new scripts one at a time. Add one, launch, play for a few minutes, then add the next. That way, when something crashes, you know exactly which file caused it.
Settings and debugging under CLEO 5
CLEO 5 handles errors much better than CLEO 4. When a script hits a problem, CLEO 5 tries to report the error and stop that script instead of taking the whole game down. Old CLEO 4 setups often just crashed to desktop with no clue why.
A few habits make debugging easier:
- Check for a log. CLEO 5 writes diagnostic output that names the failing script and opcode. Look in the game folder and the
cleofolder after a crash. - Look for the config file. CLEO 5 ships with a configuration file that controls things like logging and legacy behaviour. Read the comments in it before changing anything.
- Use the debug plugin when writing scripts. The CLEO 5 package includes debugging utilities aimed at script authors; regular players can ignore them.
If you want to write or edit scripts yourself, install Sanny Builder by Seemann. It compiles source into .cs files and can decompile existing scripts so you can see how they work. Set Sanny Builder’s game mode to San Andreas and point it at your game folder, and it will compile directly into cleo\.
Compatibility and conflicts
Most problems come from four places.
Wrong executable. Covered above, and still the top cause. Anything other than 1.0 US means CLEO 5 won’t load.
Two scripts editing the same thing. Two scripts that both change the camera, the HUD, or the player’s movement will fight. Neither one “wins” cleanly. Usually you get flickering, stuck animations or a crash. Pick one.
CLEO 4-era scripts. The CLEO 5 team has put real work into compatibility, and most old scripts run fine. A minority relied on undocumented CLEO 4 behaviour and break. Check the script’s page for a CLEO 5 update before you blame the library.
Multiplayer. SA-MP and other multiplayer clients have their own rules on CLEO, and many servers ban it outright because scripts can give unfair advantages. Keep your CLEO folder for single-player. Running scripts on a public server is the fastest way to get banned, and cheating in online play ruins things for everyone else.
SilentPatch by Silent is safe alongside CLEO and is close to mandatory on modern Windows. It fixes many engine bugs that otherwise get blamed on scripts.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No CLEO version on main menu | ASI loader missing or broken | Reinstall one ASI loader; check vorbisFile.dll and vorbisHooked.dll |
| Crash right after the splash screens | Wrong gta_sa.exe version | Confirm v1.0 US by file size; downgrade your own copy |
| Crash when loading a save | A script stored data that no longer matches | Remove recently added scripts; clear that script’s entry in cleo_saves or start a new game |
| Script loads but does nothing | Wrong key, missing plugin or missing .fxt | Reread the readme; add required .cleo plugins and text files |
| Error naming an opcode | Script needs a plugin you don’t have | Install the plugin listed in the script’s requirements |
| Game worked, then broke after “verifying files” on Steam | Steam restored the newer executable | Restore your 1.0 US backup; disable automatic updates |
| Two features glitching together | Script conflict | Remove one; test them separately |
Uninstalling CLEO
To remove a single script, delete its .cs file from cleo\ (and any .fxt, .ini or plugin it added, if nothing else needs them). Load a save made before you installed it if possible; some scripts leave data in the save.
To remove CLEO entirely, delete cleo.asi and the cleo folder. You can leave the ASI loader if other .asi mods depend on it. If you want a completely clean game, restore the backup you made in step 2. That’s the reason you made it.
FAQ
Is CLEO safe to use?
The library itself is safe and open-source on GitHub. The risk is in scripts, which are compiled code from many different authors. Stick to established sites, scan downloads and back up your saves.
Does CLEO work with the GTA San Andreas Definitive Edition?
No. Regular CLEO only supports the classic PC game. CLEO Redux by Seemann is the project that supports the Definitive Edition, and it uses its own script formats.
Does CLEO work on the Steam version?
Not directly. The current Steam and Rockstar Launcher builds use a different executable. You need to downgrade your own copy to v1.0 US with a community patcher before CLEO 5 will load.
Should I use CLEO 4 or CLEO 5?
Use CLEO 5 for new setups. It’s actively maintained, reports errors instead of crashing silently and runs most CLEO 4 scripts. Keep CLEO 4 only for a specific old script that refuses to work under 5.
Can I use CLEO with SA-MP?
Many SA-MP servers ban CLEO, and using scripts to gain an advantage online is cheating. Keep CLEO for single-player.
What’s the difference between .cs and .cm files?
A .cs file starts automatically when you load a game. A .cm file is a custom mission that only runs when another script or command launches it.
Do CLEO scripts affect the built-in cheat codes?
No. The vanilla San Andreas cheat codes still work with CLEO installed. Some scripts use typed cheat-style strings as their own triggers, so check the readme to avoid overlaps.
