# How to Install ESX Legacy Framework on Your FiveM Server (/docs/fivem/install-esx)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Files, Folder, File } from 'fumadocs-ui/components/files';

**ESX Legacy** is the leading open-source roleplay framework for FiveM. It provides a complete RP foundation: player identity, multicharacter system, jobs (police, EMS, taxi, mechanic), economy with bank accounts, inventory, vehicle ownership, garages, properties, clothing, and more.

Prerequisites [#prerequisites]

Before installing ESX you need:

* A **MySQL database** — create one in the **Databases** tab on the [XGamingServer Panel](https://panel.xgamingserver.com). See [Database Setup](/docs/fivem/database-setup)
* **OneSync enabled** — ESX 1.7.5+ requires it. Set `set onesync on` in server.cfg
* **oxmysql** — the MySQL connector ESX depends on (the txAdmin recipe installs this automatically)

Install ESX [#install-esx]

<Tabs items={['Via txAdmin Recipe (Recommended)', 'Manual Install']}>
  <Tab value="Via txAdmin Recipe (Recommended)">
    The txAdmin recipe is the easiest method — it downloads and configures everything automatically.

    <Steps>
      <Step>
        Open txAdmin Server Deployer [#open-txadmin-server-deployer]

        Access txAdmin through your panel (usually via the **Console** or a direct txAdmin URL). Go to **Server Deployer** → **Popular Recipes**.
      </Step>

      <Step>
        Select "ESX Legacy" [#select-esx-legacy]

        Find the recipe authored by **"ESX Framework"** and select it. The recipe automatically downloads and installs:

        * Default FiveM resources (chat, spawnmanager, hardcap)
        * **oxmysql** (MySQL connector)
        * **\[core]** — 16 core ESX resources (es\_extended, identity, inventory, multicharacter, etc.)
        * **\[esx\_addons]** — 32 addon resources (police job, ambulance, taxi, vehicle shop, garages, etc.)
        * **bob74\_ipl** (interior props)
        * **pma-voice** (voice chat)
        * Preconfigured `server.cfg`
      </Step>

      <Step>
        Configure the database connection [#configure-the-database-connection]

        During the recipe setup, you'll be prompted for the MySQL connection string. Use the credentials from your **Databases** tab:

        ```
        mysql://dbuser:dbpassword@127.0.0.1/dbname?waitForConnections=true&charset=utf8mb4
        ```

        Replace `dbuser`, `dbpassword`, and `dbname` with your actual database credentials from the panel.

        > If your database password contains special characters (`;`, `/`, `?`, `@`, `&`, `=`, `+`, `$`, `#`), URL-encode them or the connection will fail.
      </Step>

      <Step>
        Complete the recipe [#complete-the-recipe]

        The recipe imports `legacy.sql` into your database (creates 24 tables for players, vehicles, jobs, economy, etc.) and deploys the server. Follow the remaining prompts.
      </Step>

      <Step>
        Start the server [#start-the-server]

        Once the recipe completes, start the server. ESX is fully installed and ready.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Manual Install">
    <Steps>
      <Step>
        Download ESX core [#download-esx-core]

        Download the latest release from [github.com/esx-framework/esx\_core](https://github.com/esx-framework/esx_core). Extract the `[core]` folder into your server's `resources/` directory.
      </Step>

      <Step>
        Download ESX addons [#download-esx-addons]

        Download from [github.com/esx-framework/ESX-Legacy-Addons](https://github.com/esx-framework/ESX-Legacy-Addons). Extract the `[esx_addons]` folder into `resources/`.
      </Step>

      <Step>
        Download oxmysql [#download-oxmysql]

        Download the latest release ZIP from [github.com/overextended/oxmysql/releases](https://github.com/overextended/oxmysql/releases). Extract to `resources/[standalone]/oxmysql/`.
      </Step>

      <Step>
        Import the database [#import-the-database]

        In the **Databases** tab on the panel, create a database if you haven't already. Then import `[SQL]/legacy.sql` from the esx\_core download into your database. This creates 24 tables including `users`, `owned_vehicles`, `jobs`, `items`, `billing`, and more.
      </Step>

      <Step>
        Configure server.cfg [#configure-servercfg]

        Add these lines to your `server.cfg` (via **Files** in the sidebar):

        ```ini
        set onesync on
        set mysql_connection_string "mysql://dbuser:dbpassword@127.0.0.1/dbname?waitForConnections=true&charset=utf8mb4"

        # Default resources
        ensure chat
        ensure spawnmanager
        ensure hardcap

        # ACE permissions for ESX
        add_principal group.admin group.user
        add_ace group.admin command allow
        add_ace group.admin command.quit deny
        add_ace resource.es_extended command.add_ace allow
        add_ace resource.es_extended command.add_principal allow
        add_ace resource.es_extended command.remove_principal allow
        add_ace resource.es_extended command.stop allow

        # MySQL
        ensure oxmysql

        # ESX
        ensure es_extended
        ensure [core]
        ensure [esx_addons]
        ```

        > **Start order matters** — `oxmysql` must start before `es_extended`.
      </Step>

      <Step>
        Start the server [#start-the-server-1]

        Start from **Console**. Watch for any database connection or resource errors.
      </Step>
    </Steps>
  </Tab>
</Tabs>

ESX Resource Structure [#esx-resource-structure]

<Files>
  <Folder name="resources" defaultOpen>
    <Folder name="[core]" defaultOpen>
      <File name="es_extended" />

      <File name="esx_identity" />

      <File name="esx_multicharacter" />

      <File name="esx_inventory" />

      <File name="esx_skin" />

      <File name="skinchanger" />

      <File name="esx_menu_default" />

      <File name="esx_menu_dialog" />

      <File name="esx_menu_list" />

      <File name="esx_notify" />

      <File name="esx_progressbar" />

      <File name="esx_textui" />

      <File name="esx_context" />

      <File name="esx_chat_theme" />

      <File name="esx_loadingscreen" />

      <File name="cron" />
    </Folder>

    <Folder name="[esx_addons]">
      <File name="esx_policejob" />

      <File name="esx_ambulancejob" />

      <File name="esx_vehicleshop" />

      <File name="esx_garage" />

      <File name="esx_banking" />

      <File name="esx_billing" />

      <File name="..." />
    </Folder>

    <Folder name="[standalone]">
      <File name="oxmysql" />
    </Folder>
  </Folder>
</Files>

Key Configuration [#key-configuration]

After installing, you can customize ESX in `[core]/es_extended/shared/config/main.lua`:

| Setting                       | Default            | Description                                |
| ----------------------------- | ------------------ | ------------------------------------------ |
| `Config.Locale`               | `"en"`             | Language                                   |
| `Config.StartingAccountMoney` | `{ bank = 50000 }` | Starting bank balance for new characters   |
| `Config.MaxWeight`            | `24`               | Max inventory weight                       |
| `Config.EnablePaycheck`       | `true`             | Enable job paychecks                       |
| `Config.PaycheckInterval`     | `7 * 60000`        | Paycheck frequency (7 minutes)             |
| `Config.EnableSocietyPayouts` | `false`            | Pay from society account instead of server |
| `Config.Identifier`           | `"license"`        | Player identifier type                     |

Common Issues [#common-issues]

| Problem                     | Fix                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------- |
| Database connection failed  | Check the connection string. Special characters in the password must be URL-encoded    |
| "Table not found" errors    | `legacy.sql` wasn't imported. Import it into your database via phpMyAdmin or the panel |
| ESX not loading             | Check that `oxmysql` starts before `es_extended` in server.cfg                         |
| OneSync errors              | Add `set onesync on` to server.cfg — required for ESX 1.7.5+                           |
| `mysql-async` errors        | ESX Legacy uses **oxmysql**, not mysql-async. Remove mysql-async if present            |
| AUTH\_SWITCH\_PLUGIN\_ERROR | MySQL 8+ issue. Set the database user to use `mysql_native_password` authentication    |

Related Guides [#related-guides]

* [Database Setup](/docs/fivem/database-setup)
* [QBCore Framework](/docs/fivem/install-qbcore)
* [ESX vs QBCore](/docs/fivem/esx-vs-qbcore)
* [Install Resources](/docs/fivem/install-resources)
* [Server Configuration](/docs/fivem/configure-your-server)