Prepare Development Environment

This document includes the installation instructions for the tools required to use and run Medusa.

Node.js

Node.js is the environment that makes it possible for Medusa to run, so you must install Node.js on your machine to start Medusa development.

Medusa supports v16+ of Node.js. You can check your Node.js version using the following command:

node -v

Windows

You can install the executable directly from the Node.js website.

For other approaches, you can check out Node.js’s guide.

Linux

You can use the following commands to install Node.js on Ubuntu:

#Ubuntu
sudo apt update
sudo apt install nodejs

For other Linux distributions, you can check out Node.js’s guide.

macOS

You can use the following commands to install Node.js on macOS:

• Homebrew
• Without Homebrew

brew install node

curl \
 "https://nodejs.org/dist/latest/node-${VERSION:-$(wget -qO- \
  https://nodejs.org/dist/latest/ | sed -nE \ 
  's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" \
  > "$HOME/Downloads/node-latest.pkg" && 
  sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"

For other approaches, you can check out Node.js’s guide.

Make sure that you have Xcode command line tools installed; if not, run the following command to install it: xcode-select --install

Git

Medusa uses Git behind the scenes when you create a new project. So, you'll have to install it on your machine to get started.

Windows

To install Git on Windows, you need to download the installable package.

Linux

For Debian/Ubuntu, you can use the following command:

apt-get install git

As for other Linux distributions, please check git’s guide.

macOS

You should already have Git installed as part of the Xcode command-line tools.

However, if for any reason you need to install it manually, you can install it with Homebrew:

brew install git

You can also check out git’s guide for more installation options.

PostgreSQL

The Medusa backend uses PostgreSQL to store data of your commerce system.

Windows

You can download the PostgreSQL Windows installer from their website.

Linux

If you’re using Ubuntu, you can use the following commands to download and install PostgreSQL:

sudo sh -c \
  'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - \
  https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get -y install postgresql

For other distributions, you can check out PostgreSQL’s website for more guides.

macOS

You can download PostgreSQL on your macOS using the installer on their website.

(Optional) Medusa CLI

Medusa provides a CLI tool that can aid your through your Medusa development. You can install it globally, or you can use it through npx.

You can install Medusa’s CLI with the following command:

• npm
• Yarn
• pnpm

npm install @medusajs/medusa-cli -g

yarn global add @medusajs/medusa-cli

pnpm add @medusajs/medusa-cli -g

To confirm that the CLI tool was installed successfully, run the following command:

medusa -v

Troubleshooting Installation

NPM Error: EACCES Permissions Errors

If you install the Medusa CLI tool with NPM and get a permission error, NPM proposes as a solution either re-installing NPM with a node version manager (nvm), or manually setting npm’s default directory.

You can check out more information in NPM’s documentation.

Powershell Error: command not found: medusa

If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error:

command not found: medusa

Try closing your Powershell window and opening a new one.

Yarn Error: command not found: medusa

If you install the Medusa CLI tool with Yarn, then try to use the CLI tool but get the error:

command not found: medusa

You have to add Yarn’s install location to the PATH variable:

• MacOS / Linux
• Windows

export PATH="$(yarn global bin):$PATH"

# MAKE SURE TO INCLUDE %path%
setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
# YOURUSERNAME is your account username

You can learn more in Yarn’s documentation.

---

Install Medusa Backend

Once you're done installing the necessary tools in your environment, check out the Medusa Backend Quickstart to install your Medusa backend.