> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Complete guide to installing Medusa using npm, yarn, pnpm, or create-medusa-app.

# Installation

This guide covers all methods for installing and setting up a Medusa project, from the automated CLI to manual installation.

## Method 1: Using create-medusa-app (Recommended)

The fastest way to get started is with `create-medusa-app`, which handles project scaffolding, database setup, and initial configuration.

### Prerequisites

* Node.js 20 or higher
* PostgreSQL 13 or higher
* npm, yarn, or pnpm

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npx create-medusa-app@latest
  ```

  ```bash yarn theme={null}
  yarn create medusa-app
  ```

  ```bash pnpm theme={null}
  pnpm create medusa-app
  ```
</CodeGroup>

<Info>
  See the [Quickstart guide](./quickstart) for detailed walkthrough of `create-medusa-app`.
</Info>

### With Options

Customize your installation with command-line options:

```bash theme={null}
npx create-medusa-app@latest my-medusa-store \
  --seed \
  --db-url postgres://localhost:5432/medusa \
  --use-pnpm
```

**Available options**:

| Option                    | Description                      |
| ------------------------- | -------------------------------- |
| `--seed`                  | Seed database with demo products |
| `--skip-db`               | Skip database creation           |
| `--db-url <url>`          | PostgreSQL connection string     |
| `--no-migrations`         | Skip database migrations         |
| `--no-browser`            | Don't open admin in browser      |
| `--use-npm`               | Use npm as package manager       |
| `--use-yarn`              | Use yarn as package manager      |
| `--use-pnpm`              | Use pnpm as package manager      |
| `--directory-path <path>` | Installation directory           |
| `--verbose`               | Show detailed logs               |

## Method 2: Manual Installation

For more control over the setup process, you can install Medusa packages manually.

### Step 1: Create Project Directory

```bash theme={null}
mkdir my-medusa-store
cd my-medusa-store
```

### Step 2: Initialize Package Manager

<CodeGroup>
  ```bash npm theme={null}
  npm init -y
  ```

  ```bash yarn theme={null}
  yarn init -y
  ```

  ```bash pnpm theme={null}
  pnpm init
  ```
</CodeGroup>

### Step 3: Install Core Packages

Install the Medusa framework and required dependencies:

<CodeGroup>
  ```bash npm theme={null}
  npm install @medusajs/framework @medusajs/medusa
  ```

  ```bash yarn theme={null}
  yarn add @medusajs/framework @medusajs/medusa
  ```

  ```bash pnpm theme={null}
  pnpm add @medusajs/framework @medusajs/medusa
  ```
</CodeGroup>

### Step 4: Install Commerce Modules

Add the commerce modules you need:

<CodeGroup>
  ```bash npm theme={null}
  npm install \
    @medusajs/product \
    @medusajs/cart \
    @medusajs/order \
    @medusajs/payment \
    @medusajs/fulfillment \
    @medusajs/customer \
    @medusajs/inventory
  ```

  ```bash yarn theme={null}
  yarn add \
    @medusajs/product \
    @medusajs/cart \
    @medusajs/order \
    @medusajs/payment \
    @medusajs/fulfillment \
    @medusajs/customer \
    @medusajs/inventory
  ```

  ```bash pnpm theme={null}
  pnpm add \
    @medusajs/product \
    @medusajs/cart \
    @medusajs/order \
    @medusajs/payment \
    @medusajs/fulfillment \
    @medusajs/customer \
    @medusajs/inventory
  ```
</CodeGroup>

<Note>
  You can install only the modules you need. See the [Commerce Modules documentation](/modules/product) for the complete list.
</Note>

### Step 5: Install Development Dependencies

<CodeGroup>
  ```bash npm theme={null}
  npm install -D typescript @types/node tsx
  ```

  ```bash yarn theme={null}
  yarn add -D typescript @types/node tsx
  ```

  ```bash pnpm theme={null}
  pnpm add -D typescript @types/node tsx
  ```
</CodeGroup>

### Step 6: Create Configuration Files

Create `medusa-config.ts` in your project root:

```typescript medusa-config.ts theme={null}
import { defineConfig, Modules } from "@medusajs/framework/utils"

export default defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS || "http://localhost:8000",
      adminCors: process.env.ADMIN_CORS || "http://localhost:9000",
      jwtSecret: process.env.JWT_SECRET || "supersecret",
      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
    },
  },
  admin: {
    path: "/app",
  },
  modules: {
    [Modules.PRODUCT]: {
      resolve: "@medusajs/product",
    },
    [Modules.CART]: {
      resolve: "@medusajs/cart",
    },
    [Modules.ORDER]: {
      resolve: "@medusajs/order",
    },
    [Modules.CUSTOMER]: {
      resolve: "@medusajs/customer",
    },
    [Modules.PAYMENT]: {
      resolve: "@medusajs/payment",
    },
    [Modules.FULFILLMENT]: {
      resolve: "@medusajs/fulfillment",
    },
    [Modules.INVENTORY]: {
      resolve: "@medusajs/inventory",
    },
  },
})
```

Create `.env` file:

```bash .env theme={null}
DATABASE_URL=postgres://postgres:postgres@localhost:5432/medusa-store
JWT_SECRET=your-secret-key-change-in-production
COOKIE_SECRET=your-cookie-secret-change-in-production
STORE_CORS=http://localhost:8000
ADMIN_CORS=http://localhost:9000
```

Create `tsconfig.json`:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "target": "ES2021",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

### Step 7: Add Scripts to package.json

Update your `package.json` with these scripts:

```json package.json theme={null}
{
  "name": "my-medusa-store",
  "version": "1.0.0",
  "scripts": {
    "dev": "medusa develop",
    "build": "medusa build",
    "start": "medusa start",
    "migrations:run": "medusa migrations run",
    "migrations:revert": "medusa migrations revert",
    "seed": "medusa seed"
  },
  "dependencies": {
    "@medusajs/framework": "^2.13.3",
    "@medusajs/medusa": "^2.13.3"
  },
  "devDependencies": {
    "@types/node": "^20.12.11",
    "typescript": "^5.6.2",
    "tsx": "^4.0.0"
  },
  "engines": {
    "node": ">=20"
  }
}
```

### Step 8: Create Source Directory

Create the basic directory structure:

```bash theme={null}
mkdir -p src/api/admin
mkdir -p src/api/store
mkdir -p src/workflows
mkdir -p src/subscribers
mkdir -p src/modules
```

### Step 9: Initialize Database

Run database migrations:

<CodeGroup>
  ```bash npm theme={null}
  npm run migrations:run
  ```

  ```bash yarn theme={null}
  yarn migrations:run
  ```

  ```bash pnpm theme={null}
  pnpm migrations:run
  ```
</CodeGroup>

### Step 10: Start Development Server

<CodeGroup>
  ```bash npm theme={null}
  npm run dev
  ```

  ```bash yarn theme={null}
  yarn dev
  ```

  ```bash pnpm theme={null}
  pnpm dev
  ```
</CodeGroup>

Your Medusa application is now running at `http://localhost:9000`!

## Database Setup

### PostgreSQL Installation

<Tabs>
  <Tab title="macOS">
    Using Homebrew:

    ```bash theme={null}
    brew install postgresql@13
    brew services start postgresql@13
    ```

    Create database:

    ```bash theme={null}
    createdb medusa-store
    ```
  </Tab>

  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt update
    sudo apt install postgresql postgresql-contrib
    sudo systemctl start postgresql
    sudo systemctl enable postgresql
    ```

    Create database:

    ```bash theme={null}
    sudo -u postgres createdb medusa-store
    ```
  </Tab>

  <Tab title="Windows">
    1. Download installer from [postgresql.org](https://www.postgresql.org/download/windows/)
    2. Run installer and follow setup wizard
    3. Use pgAdmin or command line to create database:

    ```sql theme={null}
    CREATE DATABASE medusa_store;
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker run -d \
      --name medusa-postgres \
      -e POSTGRES_USER=postgres \
      -e POSTGRES_PASSWORD=postgres \
      -e POSTGRES_DB=medusa-store \
      -p 5432:5432 \
      postgres:13
    ```
  </Tab>
</Tabs>

### Database Connection String Format

```
postgres://[user]:[password]@[host]:[port]/[database]
```

**Example**:

```
postgres://postgres:mypassword@localhost:5432/medusa-store
```

**With SSL** (for hosted databases):

```
postgres://user:password@host:5432/database?sslmode=require
```

## Installing Providers

Providers extend Medusa modules with specific implementations.

### Payment Providers

<CodeGroup>
  ```bash Stripe theme={null}
  npm install @medusajs/payment-stripe
  ```

  ```bash PayPal theme={null}
  npm install medusa-payment-paypal
  ```
</CodeGroup>

Configure in `medusa-config.ts`:

```typescript medusa-config.ts theme={null}
import { Modules } from "@medusajs/framework/utils"

export default defineConfig({
  modules: {
    [Modules.PAYMENT]: {
      resolve: "@medusajs/payment",
      options: {
        providers: [
          {
            resolve: "@medusajs/payment-stripe",
            id: "stripe",
            options: {
              apiKey: process.env.STRIPE_API_KEY,
            },
          },
        ],
      },
    },
  },
})
```

### File Storage Providers

<CodeGroup>
  ```bash Local (included) theme={null}
  npm install @medusajs/file-local
  ```

  ```bash S3 theme={null}
  npm install @medusajs/file-s3
  ```

  ```bash MinIO theme={null}
  npm install medusa-file-minio
  ```
</CodeGroup>

Configure in `medusa-config.ts`:

```typescript medusa-config.ts theme={null}
[Modules.FILE]: {
  resolve: "@medusajs/file",
  options: {
    providers: [
      {
        resolve: "@medusajs/file-s3",
        id: "s3",
        options: {
          file_url: process.env.S3_FILE_URL,
          access_key_id: process.env.S3_ACCESS_KEY_ID,
          secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
          region: process.env.S3_REGION,
          bucket: process.env.S3_BUCKET,
        },
      },
    ],
  },
},
```

### Notification Providers

<CodeGroup>
  ```bash SendGrid theme={null}
  npm install medusa-notification-sendgrid
  ```

  ```bash Mailchimp theme={null}
  npm install medusa-notification-mailchimp
  ```

  ```bash Local (included) theme={null}
  npm install @medusajs/notification-local
  ```
</CodeGroup>

## Admin Dashboard Setup

The admin dashboard is included by default. To customize:

### Install Admin SDK

```bash theme={null}
npm install @medusajs/admin-sdk
```

### Build Admin for Production

```bash theme={null}
npm run admin:build
```

### Configure Admin Path

In `medusa-config.ts`:

```typescript theme={null}
export default defineConfig({
  admin: {
    path: "/app",              // Admin URL path
    outDir: "build/admin",     // Build output directory
    backendUrl: process.env.MEDUSA_BACKEND_URL,
  },
})
```

## Environment Variables

### Required Variables

```bash .env theme={null}
# Database
DATABASE_URL=postgres://localhost:5432/medusa-store

# Security
JWT_SECRET=your-jwt-secret-key
COOKIE_SECRET=your-cookie-secret-key

# CORS
STORE_CORS=http://localhost:8000
ADMIN_CORS=http://localhost:9000
```

### Optional Variables

```bash .env theme={null}
# Redis (for caching and sessions)
REDIS_URL=redis://localhost:6379

# Email
SENDGRID_API_KEY=your-sendgrid-key
SENDGRID_FROM=noreply@yourstore.com

# Storage
S3_URL=https://s3.amazonaws.com
S3_BUCKET=medusa-uploads
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key

# Stripe
STRIPE_API_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Server
PORT=9000
NODE_ENV=development
LOG_LEVEL=info
```

## Verification

After installation, verify everything works:

### 1. Check Server Health

```bash theme={null}
curl http://localhost:9000/health
```

Expected response:

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-03-03T15:00:00.000Z"
}
```

### 2. Test API

```bash theme={null}
curl http://localhost:9000/store/products
```

### 3. Access Admin

Open `http://localhost:9000/app` in your browser.

### 4. Check Database Connection

```bash theme={null}
psql $DATABASE_URL -c "SELECT version();"
```

## Troubleshooting

<Warning>
  **"Cannot find module @medusajs/framework"**

  Ensure all packages are installed:

  ```bash theme={null}
  rm -rf node_modules package-lock.json
  npm install
  ```
</Warning>

<Warning>
  **"Database connection failed"**

  Verify PostgreSQL is running and credentials are correct:

  ```bash theme={null}
  psql $DATABASE_URL
  ```
</Warning>

<Warning>
  **"Port 9000 is already in use"**

  Change the port in your `.env`:

  ```bash theme={null}
  PORT=9001
  ```

  Or kill the process using the port:

  ```bash theme={null}
  lsof -ti:9000 | xargs kill -9
  ```
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="./quickstart">
    Follow the quickstart guide for your first steps
  </Card>

  <Card title="Architecture" icon="sitemap" href="./architecture">
    Understand Medusa's architecture and design
  </Card>

  <Card title="API Routes" icon="code" href="/development/api-routes">
    Learn to create custom API endpoints
  </Card>

  <Card title="Commerce Modules" icon="cube" href="/modules/product">
    Explore all available commerce modules
  </Card>
</CardGroup>