PrestaShop module installation from a ZIP file: step by step and what to do when it fails
PrestaShop module installation from a ZIP file takes three clicks under Modules → Module Manager: the upload button, choosing the file, and configuration. When an error appears, the cause is usually how the package is built, a file size limit on the server, or a module version that doesn't match your store. Back up the store and check where the package came from before installing.
Author: The TellMyShop team. A guide for PrestaShop store owners: the cause, the manual fix and the same work in a chat conversation.
Last updated: · 6 min read
What to check before installing a module
A module is code that runs on your server and has access to the store's database. Five minutes of checking before installing is cheaper than repairs afterwards.
- Source. Download the module from its author, from Addons or from the author's release on GitHub. Free copies of paid modules from random sites are a common way for malicious code to get into a store.
- Compatibility with your store version. The module description lists the PrestaShop and PHP versions it runs on. You can see your store's version under Advanced Parameters → Information.
- Whether you already have a module that does the same thing. Two review modules or two delivery modules are a common cause of conflicts.
- Backup. A backup of the files and database from your host or a backup module. Without one, every mistake is expensive.
- Timing. Install when the store is quiet. Try payment and delivery modules on a staging copy first.
How to install a module from a ZIP file
The PrestaShop 8 and 9 admin has a form for this in the Module Manager. The PrestaShop guide to modules describes the modules screen in general.
- Go to Modules → Module Manager.
- Click the upload a module button at the top of the page.
- Drag the ZIP file into the box or choose it from your computer. Don't unzip it first.
- Wait for the installation message. With larger modules this takes a few dozen seconds.
- Click Configure and set up the module following the author's instructions.
- Open the store in a private window. Check the home page, a product page and the basket.
- Look in Advanced Parameters → Logs to see whether any new errors appeared after the installation.
Updating from a ZIP works the same way: you upload a newer version of the same module. PrestaShop recognises that the module is already there, replaces the files and runs the upgrade scripts.
What to watch for when updating a module
An update is more than swapping files. A new version may change database tables, add new places on the page or change default settings.
- Read the author's changelog. Look for sentences about the required PHP version, new settings and template changes.
- Check whether your theme has a copy of the module's template. If it does, the new module version may look different from the author's description, or not show the new elements at all.
- Update payment and delivery modules outside shopping hours. Place a test order after the update.
- Don't jump several versions at once without a backup. Upgrade scripts are often written with the previous version in mind.
The most common errors when installing a module
| Message or symptom | Cause | What to do |
|---|---|---|
| the module is invalid, or the file doesn't look like a valid module zip | the ZIP has no module folder with a file of the same name | unzip on your computer; inside there should be one folder, e.g. mymodule/mymodule.php |
| the same error with a package from Addons | the downloaded ZIP contains the module, documentation and licence in one archive | unzip it and upload only the module's inner ZIP |
| the upload ends with an error and no description | the file is larger than the server's upload limit | raise the limit with your host or upload the module by FTP |
| the module isn't compatible with your store version | the author set a PrestaShop version range in the module | download the module version for your PrestaShop |
| a blank page or a 500 error after installation | the module needs a different PHP version or conflicts with another module | disable the module, read the error log |
| no write permission | the server doesn't allow writing to the modules folder | ask your host to set the correct folder permissions |
The PrestaShop documentation on module structure describes how a correct package is built: the module folder has the same name as the module, and the module in the ZIP must be in a subfolder. The PrestaShop developers described the problem of overly large packages in the Module Manager alerts specification, together with the PHP settings responsible for it.
If the store doesn't display after installation, start with the post on the PrestaShop 500 error. If the module works but breaks something, disable it rather than uninstalling it, as we describe in the post on disabling a module.
How to install or update a module through the chat
You give your chat (Claude or ChatGPT) a direct https link to the ZIP file, for example to a release on GitHub or to a file from the author. The chat first downloads the package for a preview and checks it before anything reaches the store: the module name and version, the source, the SHA-256 checksum and the package structure. You can't upload a file from your computer this way; a link is needed.
You: Update the payment module to 2.4.1 from this GitHub release link. Check the store before and after.
Your chat: Package preview: payment module, installed version 2.3.0, package version 2.4.1. Source: the author's release on GitHub. Structure correct, one module folder. The SHA-256 checksum is in the preview, so you can compare it with the one the author published.
Before updating I'll back up the module files. I can't reverse database changes made by the upgrade script from the history; that is what today's database backup is for. Right now the log has no errors from this module. Update?
You: Yes.
Your chat: Updated to 2.4.1. The basket and the order page respond correctly, and there are no new errors in the log.
Card status: waiting for your “yes”old version: version 2.3.0
new version: version 2.4.1
The version numbers in the example are illustrative. An example request is in the use case installing or updating a module from a ZIP package, and if something stops working after the change, in the use case disabling a module that breaks the basket.
TellMyShop Pro installs and updates modules once the Modules switch is on in the module panel. The switch lasts 24 hours and needs a database backup made the same day. The chat installs nothing without a preview and your agreement, and it will advise against a module from an uncertain source. Uninstalling a module can't be undone, so the chat suggests disabling it first. In the free TellMyShop Free version you see the list of modules with their versions and the places where they display. A comparison of the versions is on the pricing page, and we cover clearing out old modules in the post on unused modules.
Questions and answers
Where in PrestaShop do I install a module from a ZIP file?
In the Modules menu, in the Module Manager. At the top of the page there is a button to upload a module, where you drag in the ZIP file or choose it from your computer. Once uploaded, PrestaShop installs the module and offers to configure it.
What does the message that the module is invalid mean?
Most often PrestaShop didn't find a module folder with a file of the same name in the package. You may have downloaded a package with documentation instead of the module, an archive with several modules inside, or a ZIP packed inside another ZIP. Unzip the package on your computer and check what is inside.
Does updating a module from a ZIP remove its settings?
Usually not. When you upload a newer version of the same module, PrestaShop replaces the files and runs the module's upgrade scripts. The settings stay, but the scripts may change the database. So back up the store before updating, and ideally test it on a staging copy.
Can a module installation be undone?
You can disable or uninstall a new module. Uninstalling usually deletes its data and settings, so that can't be undone. With an update, the files can be restored from a backup, but you can't reverse database changes made by the upgrade script without a database backup.
Can TellMyShop Free install a module?
No. The free TellMyShop Free version only reads store reports, including the list of modules with their versions. TellMyShop Pro installs and updates modules from a ZIP package once the Modules switch is on for 24 hours.
PrestaShop is a registered trademark of PrestaShop SA. Claude is a trademark of Anthropic PBC. ChatGPT and OpenAI are trademarks of OpenAI. TellMyShop is not affiliated with these companies.