PrestaShop Folder Structure Explained: What Every Directory Does and When You Need It

Why Understanding the Folder Structure Matters

PrestaShop is a large application. A typical installation contains over 30,000 files across hundreds of directories. Most store owners never need to look at the filesystem. But if you develop modules, customize themes, debug issues, or manage your own server, knowing which directory does what saves hours of searching and prevents costly mistakes.

This guide covers the most important directories in a PrestaShop 1.7.x, 8.x, or 9.x installation. We start with the directories you will interact with most and work down to the ones you should leave alone.

/modules/ -- The Heart of PrestaShop Customization

This is the directory you will interact with most. Every module -- whether installed from the marketplace, uploaded as a ZIP, or developed custom -- lives here as a subdirectory.

modules/
  ps_emailsubscription/       -- PrestaShop native module
  mprcheckoutrevolution/      -- third-party module
  mymodule/                   -- your custom module
    mymodule.php              -- main module file (required)
    config.xml                -- cached module metadata
    views/
      templates/              -- Smarty templates
      css/                    -- stylesheets
      js/                     -- JavaScript
    controllers/
      front/                  -- front office controllers
      admin/                  -- admin controllers
    sql/                      -- install/upgrade SQL
    upgrade/                  -- version upgrade scripts
    translations/             -- translation files
    vendor/                   -- Composer dependencies

Key rules:

• The main PHP file must have the exact same name as the directory: modules/mymodule/mymodule.php
• The class name inside must match too: class Mymodule extends Module
• Never edit native PS modules (prefixed ps_) -- updates will overwrite your changes. Use hooks, overrides, or theme template overrides instead
• Module files must be owned by the web server user (www-data on most Linux setups) for uploads and cache generation to work

When you need this directory: Installing modules, developing modules, debugging module issues, checking which modules are installed, reviewing module source code.

/themes/ -- Visual Appearance and Templates

All front-office visual output is controlled by themes. Each theme is a subdirectory containing templates, assets, and configuration.

themes/
  classic/                    -- PS default theme (1.7/8)
    config/theme.yml          -- theme metadata, asset registration
    templates/                -- Smarty .tpl files
      catalog/                -- product, category pages
      checkout/               -- cart, checkout flow
      cms/                    -- CMS pages
      customer/               -- account pages
      _partials/              -- header, footer, notifications
      layouts/                -- page layout wrappers
    assets/
      css/                    -- compiled CSS
      js/                     -- compiled JS
      img/                    -- theme images (icons, placeholders)
    modules/                  -- module template overrides
  hummingbird/                -- PS 9 default theme
  my-child-theme/             -- your child theme

Key rules:

• Never edit the parent theme directly. Create a child theme that inherits from the parent and override only what you change.
• The active theme is set in Back Office > Design > Theme & Logo
• modules/ inside a theme takes priority over the module's own templates -- this is how themes customize module output
• PrestaShop 9 uses Hummingbird (Bootstrap 5, CSS layers). PrestaShop 1.7/8 uses Classic (Bootstrap 4).

When you need this directory: Customizing the store's appearance, creating child themes, overriding module templates, debugging template issues.

/config/ -- Configuration Files

Core configuration that PrestaShop reads on every request.

config/
  config.inc.php              -- NEVER EDIT: auto-generated, loads settings.inc.php
  settings.inc.php            -- database credentials, cookie key, PS version
  defines.inc.php             -- path constants, debug flags
  smarty.config.inc.php       -- Smarty template engine configuration
  autoload.php                -- Composer autoloader bootstrap

Key files:

• settings.inc.php -- Contains your database host, name, user, password, and the cookie encryption key. This file is generated during installation. Back this up. If you lose the cookie key, all existing customer sessions and employee sessions become invalid.
• defines.inc.php -- Where you toggle debug mode: set _PS_MODE_DEV_ to true for development (shows errors), false for production. Also contains _PS_CACHE_ENABLED_ and other runtime flags.

When you need this directory: Setting up a new installation, changing database credentials, toggling debug mode, troubleshooting connection issues.

/var/ -- Cache, Logs, and Temporary Files

PrestaShop's runtime data. This directory grows over time and can be safely cleared (except logs you want to keep).

var/
  cache/
    prod/                     -- production cache
      smarty/
        compile/              -- compiled Smarty templates
        cache/                -- Smarty output cache
      ContainerProdDebugProjectContainer.php  -- Symfony DI container
    dev/                      -- development cache (when _PS_MODE_DEV_ = true)
  logs/
    prod.log                  -- Symfony/PS error logs
    dev.log                   -- development mode logs

Key operations:

• Clear cache: rm -rf var/cache/prod/* -- the single most common fix for "I changed something but nothing happened"
• Alternatively: php bin/console cache:clear --env=prod
• The Smarty compile directory stores pre-compiled templates. If a template change doesn't appear, delete var/cache/prod/smarty/compile/*
• Check logs: var/logs/prod.log is the first place to look when something breaks. It contains PHP errors, Symfony exceptions, and module errors.

When you need this directory: Clearing cache after changes, debugging errors via logs, freeing disk space on small servers.

/classes/ -- Core Business Logic (Legacy)

PrestaShop's original object model. Each file is a PHP class representing a business entity or utility.

classes/
  Product.php                 -- Product entity (attributes, prices, stock)
  Category.php                -- Category entity
  Cart.php                    -- Shopping cart logic
  Order.php                   -- Order entity
  Customer.php                -- Customer entity
  Module.php                  -- Base module class (install, hooks, config)
  Tools.php                   -- Utility functions (redirect, getValue, etc.)
  Db.php                      -- Database abstraction
  ObjectModel.php             -- Base ORM class
  shop/
    Shop.php                  -- Multi-shop logic
  tax/
    Tax.php                   -- Tax calculation
  stock/
    StockAvailable.php        -- Stock management

Key rules:

• Never edit these files directly. Use the /override/classes/ mechanism if you must change core behavior (but overrides have their own problems -- prefer hooks and modules).
• In PS 1.7+, many of these classes are being gradually replaced by Symfony services in /src/. Both systems coexist.
• ObjectModel is the base class for all entities. Understanding it is essential for module development -- it provides add(), update(), delete(), getFields(), and validation.

When you need this directory: Understanding how PrestaShop calculates prices, manages stock, processes orders. Reading (not editing) these files is how you learn the internal API.

/controllers/ -- Request Handling

Controllers process HTTP requests and render pages. PrestaShop has two sets: front office and admin.

controllers/
  front/
    ProductController.php     -- product page
    CategoryController.php    -- category listing
    CartController.php        -- cart operations
    OrderController.php       -- checkout steps
    CmsController.php         -- CMS pages
    SearchController.php      -- search results
  admin/
    AdminProductsController.php
    AdminOrdersController.php
    AdminCustomersController.php

Key rules:

• Front controllers extend FrontController. Admin controllers extend AdminController.
• In PS 1.7+, admin controllers are being migrated to Symfony (in /src/PrestaShopBundle/Controller/). Some admin pages use the new Symfony controllers, others still use the legacy ones here. Both coexist.
• Module controllers live in modules/yourmodule/controllers/, not here.

When you need this directory: Understanding how a specific page works, debugging page-level issues, finding which hooks are available on which page (controllers call Hook::exec()).

/src/ -- Symfony Layer (PS 1.7+)

The modern architecture layer. PrestaShop has been gradually migrating from the legacy /classes/ + /controllers/ pattern to Symfony since version 1.7.

src/
  Adapter/                    -- bridges between legacy and Symfony
  Core/
    Domain/                   -- CQRS commands and queries
      Product/
        Command/              -- CreateProduct, UpdateProduct, etc.
        Query/                -- GetProductForEditing, etc.
    Grid/                     -- admin list/grid definitions
    Form/                     -- admin form definitions
  PrestaShopBundle/
    Controller/               -- Symfony admin controllers
    Entity/                   -- Doctrine entities
    Form/                     -- Form types
    Translation/              -- Translation system
    Twig/                     -- Twig extensions for admin

Key rules:

• This directory grows with each PS version as more features migrate to Symfony
• The Adapter/ layer is critical -- it wraps legacy classes so Symfony services can use them
• In PS 9, most admin pages are fully Symfony. In PS 1.7/8, it is a mix of legacy and Symfony.
• Module developers rarely need to modify anything here -- interact with it through Symfony services registered in your module's services.yml

When you need this directory: Advanced module development using Symfony services, understanding the CQRS pattern for product/order management in PS 8+, contributing to PrestaShop core.

/override/ -- The Override System

PrestaShop's mechanism for modifying core behavior without editing core files.

override/
  classes/
    Product.php               -- overrides classes/Product.php
    Cart.php                  -- overrides classes/Cart.php
  controllers/
    front/
      ProductController.php   -- overrides controllers/front/ProductController.php
    admin/
      AdminProductsController.php

Key rules:

• Override classes extend the original and override specific methods
• Only one override per class is possible. If two modules try to override the same class, only the last one wins. This is why overrides are fragile -- module conflicts are guaranteed in active stores.
• After adding or removing overrides, regenerate the class index: delete var/cache/prod/class_index.php and clear cache
• PS 9 deprecates the override system. Prefer hooks, Symfony service decoration, or CQRS commands for new development.
• Overrides can cause mysterious bugs that are hard to trace. Always check override/ when debugging unexpected behavior.

When you need this directory: As a last resort when hooks don't provide the control you need. Always prefer hooks and module-based approaches. Read our Hooks & Overrides reference for the full picture.

/img/ -- Product and Content Images

img/
  p/                          -- product images (organized by ID digits)
    1/2/3/                    -- product ID 123's images
      123.jpg                 -- original
      123-home_default.jpg    -- resized for homepage
      123-large_default.jpg   -- resized for product page
  c/                          -- category images
  m/                          -- manufacturer/brand logos
  s/                          -- supplier logos
  cms/                        -- CMS page images (uploaded via editor)
  l/                          -- language flag icons
  tmp/                        -- temporary uploads

Key rules:

• Product images are stored with a path derived from the product ID digits: product 123 → img/p/1/2/3/. This distributes files across directories to avoid filesystem limits.
• Image regeneration (Back Office > Design > Image Settings > Regenerate) recreates all resized versions from originals. This can take hours on large catalogs.
• Back up this directory. Product images cannot be regenerated if originals are lost.
• WebP versions are generated alongside JPG/PNG in PS 8+ when enabled.

When you need this directory: Debugging missing product images, checking image quality, bulk image operations, server migration (this is often the largest directory by file count).

/app/ -- Symfony Application Kernel

app/
  AppKernel.php               -- Symfony kernel, registers bundles
  config/
    config.yml                -- Symfony service configuration
    parameters.php            -- auto-generated from settings.inc.php
    routing.yml               -- URL routing definitions
    security.yml              -- authentication/authorization
    services.yml              -- service container definitions

Key rules:

• AppKernel.php is the entry point for the Symfony side of PrestaShop. It registers all bundles including module bundles.
• config/routing.yml defines admin URL patterns. Module admin routes are registered separately via the module's own routing files.
• In PS 9, the kernel has been significantly refactored. parameters.php generation may differ.

When you need this directory: Advanced debugging of Symfony routing, service container issues, or authentication problems. Most developers never touch this directly.

/translations/ -- Core Translation Files

translations/
  default/                    -- default English strings
  en-US/                      -- US English
  fr-FR/                      -- French
  de-DE/                      -- German
    ShopTheme.fr-FR.xlf       -- front office translations
    AdminNavigation.fr-FR.xlf -- admin menu translations

Key rules:

• Core translations use XLIFF format (.xlf). Module translations use PHP arrays or XLIFF depending on the PS version.
• Translation packs are installed via Back Office > International > Translations or php bin/console prestashop:translation:export
• Database-stored translations (edited in the back office) take priority over file-based translations.

Directories You Should Never Modify

These directories are part of PrestaShop's core infrastructure. Editing them directly means your changes will be lost on update, and you risk breaking the entire installation:

• /vendor/ -- Composer dependencies (Symfony, Doctrine, etc.). Managed by composer install. Never edit.
• /bin/ -- Console commands (bin/console). Run them, don't edit them.
• /tools/ -- Build and maintenance scripts. Internal use.
• /install/ -- Installation wizard. Deleted after installation (should be, for security).
• /admin-dev/ (or your renamed admin folder) -- Admin entry point. Rename for security, but don't edit the files inside.
• /webservice/ -- REST API endpoint. Configured via back office, not by editing files.

Quick Reference: Where to Find What

What Changes Between PS Versions

The overall trend is clear: PrestaShop is moving from the legacy architecture (/classes/ + /controllers/ + /override/) toward Symfony (/src/ + service decoration + CQRS). New module development should target the Symfony patterns where available, while maintaining backward compatibility with 1.7 through version-guarded code.

This Is Part 1 of a Series

This overview gives you the map. The following articles in this series will take you inside each directory with the depth that a reference guide demands -- file by file, pattern by pattern, with real examples from production stores.

The PrestaShop Architecture Series:

1. Folder Structure Overview (this article) -- what every directory does at a glance
2. /themes/ Deep Dive -- template resolution, asset pipeline, child theme internals, Hummingbird vs Classic, CSS layers, how Smarty renders a page from request to HTML
3. /modules/ Deep Dive -- module lifecycle, hook registration, upgrade scripts, the install/uninstall chain, how config.xml caching works, autoloading patterns
4. /classes/ and /src/ Deep Dive -- ObjectModel internals, how legacy and Symfony coexist, the Adapter layer, CQRS command/query patterns in PS 8/9
5. /controllers/ Deep Dive -- front vs admin controllers, Symfony migration status per page, routing, how hooks are called per controller
6. /config/ and /var/ Deep Dive -- configuration loading sequence, cache layers (Smarty, Symfony, OPcache, Redis), debug flags, the defines.inc.php reference
7. /override/ Deep Dive -- how the override system works internally, class_index.php, why it conflicts, what replaces it in PS 9, when to use it vs hooks
8. /img/ Deep Dive -- image storage by ID digits, regeneration pipeline, WebP generation, CDN integration, the image type system

Each article is written from the perspective of someone who has built and maintained 140+ PrestaShop modules across PS 1.7, 8, and 9. This is not documentation rewritten from the official docs -- it is practical knowledge from years of debugging, profiling, and building production systems.