Skip to main content
This guide is for new installations only. If you’re upgrading from a previous version, see the Upgrade Guide instead.

​
Installation Methods

Choose the installation method that best fits your needs:

Linux/Unix

Production server installation using cPanel or FTP

Docker

Local development environment (recommended)

Windows

Windows server or local development

​
Pre-Installation Checklist

Before you begin, ensure you have:
  • ✅ PHP 8.0.2 or higher installed
  • ✅ MySQL database created with a user assigned
  • ✅ Required PHP extensions enabled: curl, gd, zip
  • ✅ FTP/SSH access to your server (for manual installation)
  • ✅ Downloaded the latest OpenCart release
Never use your MySQL root username and password for OpenCart. Always create a dedicated database user with appropriate permissions.

​
Linux/Unix Installation

1

Upload Files

Upload all files and folders from the upload/ directory to your web root:
  • cPanel: public_html/
  • Plesk: httpdocs/
  • Other: Your server’s document root
# Example using SCP
scp -r upload/* [email protected]:/path/to/public_html/
2

Set Permissions

Ensure your web user has read, write, and execute permissions:
# Rename configuration files
mv config-dist.php config.php
mv admin/config-dist.php admin/config.php

# Set writable permissions
chmod 0777 config.php
chmod 0777 admin/config.php
After installation is complete, you should change these permissions to 0644 for security:
chmod 0644 config.php
chmod 0644 admin/config.php
3

Prepare Database

Create a MySQL database and user:
CREATE DATABASE opencart_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'opencart_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON opencart_db.* TO 'opencart_user'@'localhost';
FLUSH PRIVILEGES;
4

Run Web Installer

Visit your store homepage in a web browser:
http://www.example.com
# or if in a subdirectory:
http://www.example.com/store/
You’ll be redirected to the installation wizard. Follow the on-screen instructions:
  1. Accept the license agreement
  2. Verify system requirements
  3. Enter database connection details
  4. Create admin account
  5. Complete installation
5

Post-Installation

After successful installation:
# Delete the install directory (REQUIRED)
rm -rf install/

# If you have a vendor folder, move it above webroot
# (applies to compiled versions only)
mv vendor/ ../vendor/
You must delete the /install/ directory after installation for security reasons. Your store will not function properly until this is done.
OpenCart includes a complete Docker-based development environment.

​
Prerequisites

  • Docker Desktop or Docker Engine with Docker Compose v2
  • make utility (pre-installed on macOS/Linux)
  • WSL 2 (strongly recommended for Windows users)
For Windows users: Clone the repository inside your WSL distribution (e.g., Ubuntu) for optimal performance. Without WSL 2, file system performance will be extremely slow.

​
Quick Start with Docker

1

Clone Repository

git clone https://github.com/opencart/opencart.git
cd opencart
2

Initialize Environment

make init
This copies docker/.env.docker.example to docker/.env.docker
3

Build Images

make build
Builds PHP, Apache, and MySQL Docker images
4

Start Services

make up
Starts all services. Your store will be available at http://localhost
5

Complete Web Installation

Open http://localhost in your browser and follow the installation wizard

​
Docker Commands Reference

# View all available commands
make help

# Stop the environment
make down

# View logs from all services
make logs

# Enter the PHP container
make php

# Restart services
make restart

​
Using Optional Services

Enable additional services using Docker Compose profiles: 
# Start with Adminer (database management UI)
make up profiles="adminer"

# Start with Redis and Memcached
make up profiles="redis memcached"

# Start all optional services
make up profiles="adminer redis memcached postgres"
Access Adminer at http://localhost:8080 when enabled

​
Changing PHP Version

Edit docker/.env.docker to change the PHP version: 
PHP_VERSION=8.2
Then rebuild: 
make build
make up

​
Windows Installation

1

Upload Files

Upload all files from the upload/ folder to your server directory:
C:\inetpub\wwwroot\store\
# or
C:\wwwroot\
2

Rename Configuration Files

config-dist.php → config.php
admin/config-dist.php → admin/config.php
Set Read and Write permissions for these files in Windows File Properties
3

Enable PHP Extensions

Ensure these extensions are enabled in php.ini:
extension=curl
extension=gd
extension=zip
extension=mbstring
4

Create Database

Create a MySQL database and user (do not use root credentials)
5

Run Installer

Visit your site in a browser and follow the installation wizard
6

Delete Install Directory

After completion, delete the install/ directory

​
Local Development Alternatives

If you prefer not to use Docker, these all-in-one solutions work well with OpenCart:

​
Post-Installation Configuration

​
Going Live

Before launching your production store, disable error display: 
// Find:
$_['error_display'] = true;

// Replace with:
$_['error_display'] = false;

​
Initial Store Configuration

  1. Login to Admin Panel: http://yourstore.com/admin
  2. System → Settings: Configure your store details
  3. Extensions → Extensions: Install payment and shipping methods
  4. Design → Themes: Select and configure your theme
  5. System → Users → User Groups: Verify admin permissions

​
Troubleshooting

If hosting on GoDaddy, you may need to rename php.ini to user.iniGoDaddy uses non-standard file naming conventions for PHP configuration.
  • Ensure you’ve deleted the /install/ directory
  • Check file permissions on config.php files
  • Enable error display temporarily to see the actual error
  • Check PHP error logs for details
  • Verify database credentials in config.php
  • Ensure MySQL service is running
  • Check that database user has proper privileges
  • Confirm database host (usually localhost)
  • Check file permissions on /image/ directory
  • Verify web server is configured to serve static files
  • Clear browser cache
  • Check for .htaccess issues on Apache

​
Next Steps

Now that OpenCart is installed:

Quick Start Guide

Configure your store and add your first products

Theme Customization

Customize the look and feel of your store

Build docs developers (and LLMs) love

Get started for freeTalk to us