How to Install Remotion: A Complete Guide to Setup and Configuration

Run npx create-video@latest to scaffold a new Remotion project with all dependencies pinned to compatible versions.

Remotion is a React framework for creating programmatic video content, distributed as the open-source repository remotion-dev/remotion. Whether you are starting a fresh project or integrating video generation into an existing React application, this guide covers every method to install Remotion correctly, including version alignment strategies and verification steps.

Prerequisites for Installing Remotion

Before running any installation commands, ensure your environment meets the minimum requirements defined in the repository's root package.json.

Node.js Version Requirements

Remotion requires Node.js version 16 or higher. The engines field in package.json explicitly enforces this constraint:

// package.json (root)
"engines": {
  "node": ">=16"
}

You can verify your Node.js version by running node -v in your terminal. If you need to upgrade, download the latest LTS version from the official Node.js website.

Method 1: Quick Start with the Remotion CLI (Recommended)

The fastest way to install Remotion is using the create-video CLI tool. This method is documented in packages/core/README.md and the root README.md.

Run the following command in an empty directory:

npx create-video@latest

This command performs three critical actions:

1. Scaffolds a project structure with a minimal Remotion composition, TypeScript configuration, and Webpack setup.
2. Installs remotion and @remotion/* packages at the exact same version number, preventing dependency mismatches.
3. Generates npm scripts for development and rendering.

The CLI automatically handles the complexity of the monorepo structure, ensuring that core functionality and optional plugins are compatible.

Method 2: Manual Installation in Existing Projects

If you are adding Remotion to an existing React or Node.js project, you must manually install the core library and any optional packages.

Installing the Core Library

Install the main remotion package, which contains the core React components and rendering API:

npm install remotion --save-exact

The core library is located in packages/core/ and exports essential components like Composition, Video, and useVideoConfig.

Adding Optional Packages

Remotion's architecture separates features into optional packages under the @remotion namespace. Install only what you need:

# For the Player component (embed videos in React apps)

npm install @remotion/player --save-exact

# For 3D rendering with React Three Fiber

npm install @remotion/three --save-exact

# For Tailwind CSS integration

npm install @remotion/tailwind --save-exact

Each package README (e.g., packages/player/README.md, packages/three/README.md) documents its specific installation requirements.

Version Alignment Strategy

Critical: All remotion and @remotion/* packages must share the exact same version number. The monorepo uses a single version source defined in packages/core/package.json.

Always use the --save-exact flag to prevent npm from adding caret (^) or tilde (~) ranges, which could lead to version mismatches.

To install a specific version (e.g., 4.0.422 as found in the core package):

npm install [email protected] --save-exact
npm install @remotion/[email protected] --save-exact

Verifying Your Remotion Installation

After installation, verify that Remotion is configured correctly by running the development server:

npm run dev

This command executes remotion preview, which starts a Webpack development server on a local port. You should see the Remotion Studio interface with your compositions listed.

To test the rendering pipeline:

npm run build

This produces a bundled video file in the dist/ directory, confirming that the core rendering engine and dependencies are functioning.

Understanding the Remotion Package Architecture

Understanding the monorepo structure helps troubleshoot installation issues:

• packages/core – Contains the essential React API (Composition, Video, useVideoConfig) and the server-side rendering runtime. This is what you install when you run npm install remotion.
• packages/create-video – A scaffolding CLI that does not contain runtime code. It generates a project folder and installs the correct versions of core and plugins.
• packages/* (plugins) – Optional features like @remotion/player (embeddable player UI) and @remotion/three (3D support). Each declares remotion as a peer dependency.

This modular design keeps your bundle size minimal while allowing you to add specific capabilities as needed.

Code Examples

Basic Composition Setup

After installation, create your first video component in src/HelloWorld.tsx:

import {Composition} from 'remotion';

const HelloWorld = () => {
  return (
    <div
      style={{
        fontSize: 80,
        color: 'white',
        background: 'black',
        width: '100%',
        height: '100%',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      Hello Remotion!
    </div>
  );
};

export const RemotionVideo = () => (
  <Composition
    id="HelloWorld"
    component={HelloWorld}
    durationInFrames={150}
    fps={30}
    width={1080}
    height={1920}
  />
);

Rendering from CLI

Use the installed CLI to render your composition to a video file:

npx remotion render src/HelloWorld.tsx HelloWorld out/video.mp4

This command uses the core runtime from packages/core to server-side render the React component into an MP4 file using FFmpeg.

Embedding the Player

If you installed @remotion/player, you can embed the video in any React application:

import {Player} from '@remotion/player';
import {HelloWorld} from './HelloWorld';

export const PlayerDemo = () => (
  <Player
    component={HelloWorld}
    durationInFrames={150}
    fps={30}
    width={1080}
    height={1920}
    controls
  />
);

Summary

• Use npx create-video@latest for the fastest installation path; it handles version alignment and project scaffolding automatically.
• Manual installation requires npm install remotion --save-exact followed by any optional @remotion/* packages, all pinned to the identical version number.
• Node.js 16+ is mandatory, as enforced by the engines field in the root package.json.
• Verify installation by running npm run dev to start the Remotion Studio preview server.
• The monorepo architecture separates core functionality (packages/core) from optional plugins, allowing you to install only the features you need.

Frequently Asked Questions

What Node.js version do I need to install Remotion?

Remotion requires Node.js version 16 or higher. This requirement is explicitly defined in the engines field of the root package.json in the remotion-dev/remotion repository. Attempting to install with an older version will trigger an engine compatibility error from npm.

Can I install Remotion in an existing React project?

Yes, you can add Remotion to an existing project by manually installing the core library with npm install remotion --save-exact. You may also need to install specific @remotion/* packages depending on your use case, such as @remotion/player for embedding videos or @remotion/three for 3D content. Ensure all packages share the exact same version number to avoid runtime errors.

Why should I use --save-exact when installing Remotion packages?

You should use --save-exact because Remotion is a monorepo where all packages (remotion, @remotion/player, @remotion/three, etc.) share a single version number (e.g., 4.0.422). Using exact versions prevents npm from installing incompatible minor or patch versions that could break the peer dependency relationships between packages. This practice is documented in the README files of individual packages like @remotion/tailwind.

How do I check if Remotion is installed correctly?

After installation, run npm run dev in your project directory. This executes the remotion preview command, which starts a Webpack development server and opens the Remotion Studio interface. If the server starts without errors and you can see your compositions listed, the installation is successful. You can also run npm run build to verify that the rendering pipeline works correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}