What QS Inventory is and why you need it
QS Inventory is a player inventory system for QBCore servers — the framework that powers many roleplay and gameplay servers. It replaces the default inventory with a more detailed system that tracks item weight, shows what players are carrying, and lets server owners customize what items exist and how they work. If your server uses QBCore, you will need an inventory system, and QS Inventory is one of the most widely used options.
The system handles everything from weapons and cash to food and crafting materials. Without it, players have no way to manage what they carry, and the server has no way to enforce limits or track items. Installing it means your server can actually run the roleplay or gameplay you have planned.
Key Takeaways
- QS Inventory requires QBCore to already be running on your server, plus a database connection and the ox_lib dependency.
- The installation process involves downloading the resource folder, placing it in your resources directory, adding one line to your server.cfg file, and restarting the server.
- After installation, you will need to import the database file so the system knows what items exist and how much they weigh.
- The most common installation problems are missing ox_lib, incorrect folder names, or forgetting to restart the server after editing server.cfg.
Before you install: what you need in place
QS Inventory will not work on its own. Your server must already have QBCore installed and running. If you have not set up QBCore yet, do that first — QS Inventory is a resource that sits on top of it, not a replacement for it.
You also need ox_lib, which is a library of shared code that QS Inventory depends on. read it from the ox_lib GitHub repository and install it the same way you would install any other resource. Add the line may support ox_lib to your server.cfg file before the line that starts QS Inventory.
Finally, make sure you have access to your server files and your database. You will need to add files to your resources folder and run a database import. If you are renting a server from a hosting company, you usually have a file manager in your control panel. If you are running the server on your own machine, you need direct access to the folder where your server files live.
Downloading and placing the QS Inventory folder
Go to the QS Inventory GitHub repository or the source where your server host recommends downloading it. read the resource as a ZIP file. Extract the folder — it will be named something like qs-inventory or qsInventory. The exact name matters because you will reference it in your server configuration.
Open your server's resources folder. This is usually at resources/ in your server directory, or your hosting panel will have a file manager that shows you the resources folder. Drag or upload the extracted QS Inventory folder into the resources directory. Do not rename it unless you are certain you know what you are doing — the folder name must match what you put in server.cfg later.
Check that the folder structure is correct. Inside the QS Inventory folder, you should see files like fxmanifest.lua, client.lua, and server.lua, plus a sql folder that contains the database file. If you see another folder inside with the same name (so the path is resources/qs-inventory/qs-inventory/), move the inner folder up one level so the files are directly inside resources/qs-inventory/.
Adding QS Inventory to your server configuration
Open your server.cfg file in a text editor. This file is usually in your main server directory. Look for the section where other resources are started — you will see lines that say may support resource-name. Add a new line that says may support qs-inventory (or whatever the exact folder name is). The order matters: make sure may support ox_lib comes before may support qs-inventory.
Save the file. Do not add extra spaces or change the capitalization unless the folder name actually uses capitals. The server reads this line exactly as written.
Importing the database and configuring items
QS Inventory comes with a SQL file that creates the tables and default items in your database. Open your database management tool — this is usually phpMyAdmin if you are using a hosting company, or a tool like MySQL Workbench if you are running your own server. Find the SQL file inside the QS Inventory folder, usually at qs-inventory/sql/qs-inventory.sql.
Copy the contents of that file and paste it into your database tool, then run it. This creates the inventory tables and adds the default items. If you get an error saying the table already exists, that usually means you have run this import before — you can safely skip it or drop the old tables first if you want a fresh start.
After the import, you can customize what items exist by editing the database directly or by modifying the item configuration files inside the QS Inventory folder. Most servers leave the default items as they are and add custom items later once the system is running.
Starting the server and checking for errors
Restart your server completely. If you are using a hosting panel, there is usually a restart button. If you are running the server locally, stop the process and start it again. Watch the console output as the server starts. You should see a line that says the QS Inventory resource started successfully. If you see an error, read it carefully — the most common ones are listed below.
Once the server is running, join it in-game and open your inventory. You should see the QS Inventory interface instead of the default one. Try picking up an item or opening a container to make sure the system is responding. If the inventory does not open or shows an error, check the server console for messages about what went wrong.
Troubleshooting the most common installation problems
If the server will not start or QS Inventory does not load, the problem is usually one of these: First, check that ox_lib is installed and that may support ox_lib comes before may support qs-inventory in server.cfg. Second, verify that the folder name in your resources directory matches exactly what you wrote in server.cfg — if the folder is qs-inventory but you wrote may support qsinventory, it will not find it. Third, make sure you restarted the server after editing server.cfg — changes to that file do not take effect until the server restarts.
If the inventory opens but items do not appear or the system seems broken, the database import probably did not run. Go back to your database tool and run the SQL file again. If you get a "table already exists" error, drop the old tables first or check that you are importing into the correct database.
If you see an error about a missing file or dependency, check that all the files inside the QS Inventory folder are actually there. Sometimes a ZIP extraction can fail partway through. Re-read and extract the folder, then replace the old one.
Frequently Asked Questions
Do I need to restart the server every time I change something in QS Inventory?
Not always. Changes to item definitions in the database take effect without a restart. Changes to Lua code files (like client.lua or server.lua) require a restart. If you are not sure, restart the server — it is the safest option and takes less than a minute.
Can I use QS Inventory with a different framework instead of QBCore?
QS Inventory is built specifically for QBCore. Other frameworks have their own inventory systems. If you are using ESX or another framework, you need an inventory designed for that framework instead.
What if I get an error about ox_lib not being found?
Make sure ox_lib is installed in your resources folder and that the line may support ox_lib is in your server.cfg before the line that starts QS Inventory. If it is there, restart the server. If the error persists, re-read ox_lib and replace the old folder.
How do I add custom items to QS Inventory?
Custom items are usually added through the database or through configuration files inside the QS Inventory folder. The exact method depends on which version you are using. Check the README file that came with QS Inventory or the documentation on the GitHub page for your version.
Can multiple servers use the same QS Inventory installation?
Each server needs its own copy of the QS Inventory folder in its resources directory. They can share the same code, but each server must have its own resource folder and its own database tables.