Guide · Open source

How to use Leptos: install cargo-leptos and run your first app

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Leptos is an open-source web framework written in Rust for building interactive websites and web apps. This guide shows how to install the cargo-leptos build tool, create a starter project, run it with live rebuilds, and understand the basic building blocks of a Leptos component. It is aimed at readers who already work with Rust, since the project itself notes that Rust has a steep learning curve.

Leptosleptos-rs/leptos · ★ 21.5k · MIT Install options & downloads

Quick start

1Install the Rust toolchain. Install Rust using rustup, as the README specifies.
2Install cargo-leptos. Run cargo install cargo-leptos --locked to add the build tool.
3Create a project. Run cargo leptos new --git https://github.com/leptos-rs/start-axum to generate a starter project.
4Enter the project folder. Change into the folder you created, replacing the placeholder with your project name.
5Start the dev server. Run cargo leptos watch and open http://localhost:3000/ in your browser.
6Edit a component. Change a component's view! block or signal logic and save to see live rebuilds.

Check the prerequisites

Leptos is installed through the Rust ecosystem. You need a Rust toolchain, which the README says to install via rustup, and the cargo-leptos build tool. The README's recommended way to start a real project is to use cargo-leptos together with a starter template.

Rust toolchain (installed via rustup)
cargo-leptos build tool

Install cargo-leptos

Install the build tool with cargo. The README uses the --locked flag in its command.

cargo install cargo-leptos --locked

Create a new project from the Axum starter

cargo-leptos can generate a project from a starter template. The README's recommended starter for Axum is the start-axum repository. The README also offers a starter for Actix, linked from its cargo-leptos section.

cargo leptos new --git https://github.com/leptos-rs/start-axum

Run the dev server with live rebuilds

Move into the project folder that cargo-leptos created, replacing the placeholder with your project name, then start the dev server. According to the README, the app is served at http://localhost:3000/ once it is running.

Open http://localhost:3000/ in your browser after the server starts.

cd [your project name]
cargo leptos watch

Understand a basic component

Leptos components are Rust functions marked with the #[component] attribute and returning impl IntoView. State is held in reactive signals created with signal(). The view! macro describes the HTML, using a JSX-like syntax. Event handlers are attached with on:click, and a signal's value can be placed directly in the view.

The README also shows a builder syntax as an alternative to the view! macro. It notes that the view macro expands to this builder syntax.

signal(initial_value) returns a getter and a setter.
set_value.update(...) changes the value and triggers the affected parts of the page.
mount_to_body mounts the root component in the browser.

#[component]
pub fn SimpleCounter(initial_value: i32) -> impl IntoView {
    let (value, set_value) = signal(initial_value);
    let increment = move |_| set_value.update(|value| *value += 1);

    view! {
        <div>
            <button on:click=increment>+1</button>
            <span>"Value: " {value} "!"</span>
        </div>
    }
}

Know the three rendering modes

Leptos can render apps in the browser (client-side rendering), on the server (server-side rendering), or render HTML on the server and then add interactivity in the browser (server-side rendering with hydration). The README also describes streaming of Resources and of Suspense components.

Client-side rendering: the app runs in the browser.
Server-side rendering: HTML is produced on the server.
Hydration: server-rendered HTML gets interactivity in the browser.

Use server functions for server-only code

Leptos server functions let you write server-side logic, such as database requests or authentication, next to the components that use it. The README says you can call them as if they were running in the browser, without creating and maintaining a separate REST or other API.

The README also notes a caveat about randomness: when compiling to wasm32-unknown-unknown, rand and getrandom need their JavaScript backend enabled in your own Cargo.toml. Leptos does not configure this for your app's direct dependencies.

[dependencies]
getrandom = { version = "0.2", features = ["js"] }
rand      = { version = "0.8", features = ["small_rng"] }

Find help and examples

The project links a book, API documentation on docs.rs, an examples folder, a playground, and a list of community libraries and example projects called awesome-leptos. The README describes the book as a work in progress, and it links a Common Bugs document for known issues and fixes.

Book: leptos-rs.github.io/leptos
API docs: docs.rs/leptos
Examples folder in the leptos repository
awesome-leptos for libraries and example projects

What people use it for

Building a full web app with server-side rendering and browser interactivity in a single language.
Writing server-only logic such as database calls next to the UI components that use it.
Building interactive pages where only the changed parts of the DOM update, using fine-grained reactivity.
Prototyping with the Axum or Actix starter templates from the README.

Frequently asked questions

Is Leptos free to use?

Leptos is released under the MIT licence, as listed on its project page. You can use, modify and distribute it under those terms. Check the licence file in the repository for the full text.

What do I need to install before using Leptos?

The README lists a Rust toolchain installed through rustup and the cargo-leptos build tool. You install cargo-leptos with cargo install cargo-leptos --locked. No other prerequisites are listed in the source.

Is Leptos production ready?

The project's FAQ says the APIs are basically settled and major breaking changes are not expected in architecture. It also admits there are bugs and that some features may be missing. The README says the latest release is a release candidate, so teams that need a stable release today should wait or pick another tool.

Do I need to know Rust to use Leptos?

Yes. Leptos is written in Rust and its apps are written in Rust, and the project describes Rust as having a steep learning curve. Beginners new to programming are not the intended audience.

What is the difference between Leptos and Yew, Dioxus or Sycamore?

Yew, Dioxus and Sycamore are comparable Rust web frameworks. The source does not compare them feature by feature, so check each project's documentation. Leptos is distinctive in its fine-grained reactivity, which avoids a virtual DOM, and its server functions.

Why does my Leptos build fail on wasm with rand or getrandom?

When compiling to wasm32-unknown-unknown, rand and getrandom need a JavaScript-backed randomness source. Leptos does not enable this for your own dependencies, so add the js feature to getrandom in your Cargo.toml as shown in the README.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use Leptos if you already know Rust and want to write a full web app, including server-only logic, in one language with fine-grained updates. Pick another option if you are new to programming, need a mature ecosystem, or require a stable release today, since the source describes the latest release as a release candidate.

Install options & downloads