Skip to content
Hyperfy.how

Detailed Installation

This will setup a world locally on your machine that you can then self-host.

You can start a hosted world from a hosting provider without needing to setup locally, if you prefer.

Hyperfy v2 Repo

hyperfy

World building for everyone

JavaScript

🌟Star the repo🌟

Super fresh is on dev branch

This installation page is detailed to help those who might be fresh in some of these things.

While this is as detailed as possible, and should get you going.. if you really want to learn Foundations of Web Development, The Odin Project will teach you a lot - for free!

Once you make it through this install, most of what you will do will be directly in your Hyperfy v2 world. Right now, v2 is still mid-development. So, if you are here now, keep in mind it’s early and things will change. In the near future, v2 will be much more No-code for users to build worlds.

However, one of the amazing and fun aspects of Hyperfy is the many skill-rabbitholes you start running down. So don’t be afraid, drop that imposter syndrome and learn some new things.

The community is always here to help.

Prerequisites

  • wsl2 on Windows
  • nvm - Node version manager
  • Node v22.11.0
  • git
  • Xcode Command Line Tools on Mac
  • a web browser

WSL2

‘Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting “Run as administrator”, or Start Menu> start typing ‘Command’ > Run Command Prompt as Administrator

In the terminal that opens copy this command and hit Enter:

wsl --install

This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux.’

The first time you use WSL2, it will ask you to create a username and password for your new Ubuntu Linux Distribution.

This is a password that only applies to WSL.

You can now find WSL from the Start menu. Or in the future, open Command Prompt and type wsl and it will switch to WSL2.

if you are working from Command Prompt, after typing wsl to be sure to be in the home folder of your Ubuntu distribution. To do this, you can type cd ~ and hit Enter. ~ is above your tab key using shift.

For troubleshooting WSL2 install or to learn more about it, go to WSL2-docs

Node and Node Version Manager

After getting WSL2, you will need Node and Node Version Manager nvm`.

You can first install nvm which will help you install Node.js and manage different Node versions.

in a WSL2 terminal, run

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Node.js is a tool that helps make websites and apps work quickly by efficiently handling tasks on the server side.

After you have installed nvm, you can use it to install Node. Again in your WSL2, run:

nvm install node

Once you have it, it’s just a tool accessed in the background. You won’t need to ever ‘open’ it.

For Hyperfy v2, we want to use **Node 22.11.0**. Now that nvm and node is installed, you can run:

nvm install 22.11.0

This will install Node version 22.11.0.

If this is the only Node version you you have, you are now on 22.11.0. To check or if you already have other Node version, run:

nvm use 22.11.0

Your terminal should say Using Node v22.11.0.

Success

If you get stuck with nvm, check their repo here

Cloning the Hyperfy v2 Repo

Cloning the Main Branch

Main branch is where current stable updates have been updated to. dev branch is where the newest development is ironed out and eventually gets pushed to main.

git clone https://github.com/hyperfy-xyz/hyperfy.git my-world
cd my-world
cp .env.example .env
npm install
npm run dev

Each separated below for easy copying.

git clone https://github.com/hyperfy-xyz/hyperfy.git my-world
cd my-world
cp .env.example .env
npm install
npm run dev

After above, your world is now running in http://localhost:3000/. Open in browser.

Success

When your world is not running (you kill the terminal) you can change the my-world to anyname you want for your world.

Just remember next time, you will cd 'new world name' then npm run dev

Dev Branch

To work from the dev branch:

cd my-world
git fetch origin
git checkout -t origin/dev
git pull
npm run dev

Each separated below for easy copying.

cd my-world
git fetch origin
git checkout -t origin/dev
git pull
npm run dev
Success

Your world is now running in http://localhost:3000/. Open in browser.

Start building

Hosting

When you’re ready to host, choose between:

Self-hosting
Hosting Provider
Still intimidated? Go play in the sandbox. 🎮
Visit Getting-started for docs on developing. 📖

FAQs

If you run into please feel free to join Hyperfy Discord to ask for help. The community is knowledgeable and very supportive.

Need help coding?

AI can be your friend, and the community is here to help.