Skip to main content
Skip to main content

Install Medusa Backend

This document will guide you through setting up your Medusa backend in a three steps.


Before you can install and use Medusa, you need the following tools installed on your machine:

Create a Medusa Backend


It is recommended to use Yarn for the installation process as it's much faster than using NPM.

1. Install Medusa CLI

To install the Medusa backend, you need Medusa's CLI tool. You can install it globally or, alternatively, use it through npx with npx @medusajs/medusa-cli <command>.

npm install @medusajs/medusa-cli -g

If you run into any errors while installing the CLI tool, check out the troubleshooting guide.

2. Create a new Medusa project

medusa new my-medusa-store # or npx @medusajs/medusa-cli new

You'll then be asked to specify your PostgreSQL database credentials. You can choose "Continue" to use the default credentials shown in the terminal, choose "Change credentials" to specify your PostgreSQL credentials, or choose "Skip database setup" to create the database later.


If you choose "Skip database setup" you will need to set the database configurations and run migrations later.

3. Start your Medusa backend


Make sure your PostgreSQL server is running before you run the Medusa backend.

cd my-medusa-store
medusa develop # or npx medusa develop

After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line:

curl localhost:9000/store/products
Did you set up the backend successfully?

Troubleshooting Installation

Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string
Can't Connect to PostgreSQL Docker Container
Error: connect ECONNREFUSED ::1:5432
AwilixResolutionError: Could Not Resolve X

Seed Data

For better testing, you can add demo data to your Medusa backend by running the seed command in your Medusa backend directory:

medusa seed --seed-file=data/seed.json
# or npx medusa seed --seed-file=data/seed.json

Health Route

You can access /health to get health status of your backend.

Next Steps

Was this section helpful?