Last modified: Jun 14, 2026

Install Esmerald Framework in Python

Esmerald is a modern, high-performance Python web framework. It is built on top of Starlette and Pydantic. It offers a clean and expressive way to build APIs. This guide will help you install Esmerald quickly and correctly.

We will cover everything from setting up a virtual environment to running your first Esmerald app. Follow each step carefully. This guide is perfect for beginners and experienced developers alike.

What is Esmerald Framework?

Esmerald is a powerful web framework for Python. It is designed for speed and simplicity. It uses type hints and Pydantic for validation. This makes your code more reliable and easier to maintain.

The framework supports WebSockets, HTTP/2, and background tasks. It also has built-in support for OpenAPI documentation. You can build robust APIs with minimal effort.

Prerequisites for Installation

Before you install Esmerald, make sure you have Python installed. You need Python 3.8 or higher. Check your Python version with this command:


python --version

You should see output like Python 3.10.12. If you don't have Python, download it from python.org. Also, ensure you have pip installed. Pip is the package installer for Python.

Step 1: Create a Virtual Environment

A virtual environment keeps your project dependencies isolated. This is a best practice for any Python project. It prevents conflicts between different projects.

Open your terminal or command prompt. Navigate to your project folder. Then run:


python -m venv venv

This creates a folder named venv in your project. Now activate the virtual environment. On Windows, use:


venv\Scripts\activate

On macOS or Linux, use:


source venv/bin/activate

Your terminal prompt will change to show (venv). This means the environment is active.

Step 2: Install Esmerald

With your virtual environment active, install Esmerald using pip. Run this command:


pip install esmerald

This installs Esmerald along with its dependencies. The process takes a few seconds. You will see output showing the installation progress.

To verify the installation, check the installed version:


pip show esmerald

You will see information about the package, including its version. A successful installation means you are ready to build apps.

Step 3: Create a Simple Esmerald App

Now let's create a basic application. Create a new file called app.py in your project folder. Open it in your code editor.

Write the following code:


# app.py - A simple Esmerald application

from esmerald import Esmerald, get

# Define a simple route handler
@get("/")
async def home() -> dict:
    """Return a welcome message."""
    return {"message": "Hello, Esmerald!"}

# Create the application instance
app = Esmerald(routes=[home])

This code creates a single route at the root URL. When you visit /, it returns a JSON response. The @get decorator tells Esmerald this is a GET endpoint.

Step 4: Run the Application

To run your Esmerald app, use the uvicorn server. Uvicorn is included with Esmerald. Run this command in your terminal:


uvicorn app:app --reload

The --reload flag enables auto-reloading. This means the server restarts when you change your code. This is very helpful during development.

You will see output like this:


INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     (Press CTRL+C to quit)

Open your browser and go to http://127.0.0.1:8000. You should see:


{"message":"Hello, Esmerald!"}

Step 5: Add More Routes

Let's expand your app with more endpoints. Add these routes to your app.py file:


# Add more routes to app.py

from esmerald import get, post, Esmerald

# A GET endpoint that accepts a parameter
@get("/greet/{name}")
async def greet(name: str) -> dict:
    """Greet a person by name."""
    return {"greeting": f"Hello, {name}!"}

# A POST endpoint that reads JSON body
@post("/submit")
async def submit(data: dict) -> dict:
    """Echo the submitted data."""
    return {"received": data}

# Include the new routes
app = Esmerald(routes=[home, greet, submit])

Now restart the server if needed. Test the /greet/John endpoint. You will get {"greeting":"Hello, John!"}. For the /submit endpoint, use a tool like curl or Postman to send a POST request with JSON data.

Step 6: Understand the Project Structure

For larger projects, organize your code well. A typical Esmerald project might look like this:


my_project/
├── app.py          # Main application file
├── config.py       # Configuration settings
├── routes/         # Folder for route modules
│   └── users.py    # User-related routes
├── models/         # Pydantic models
│   └── user.py     # User model
└── venv/           # Virtual environment

This structure keeps your code clean and scalable. Esmerald supports mounting sub-applications. This helps you split your API into logical parts.

Troubleshooting Common Installation Issues

Sometimes installation fails. Here are common problems and solutions:

Problem: Permission errors - You might see "Permission denied" when installing. Use pip install --user esmerald to install for your user only.

Problem: Python version too old - Esmerald requires Python 3.8+. Upgrade your Python version if needed.

Problem: Dependency conflicts - Always use a virtual environment. This avoids conflicts with system packages.

Problem: Missing C compiler - Some dependencies need a C compiler. Install build-essential on Linux or Xcode Command Line Tools on macOS.

Best Practices for Esmerald Development

Follow these tips for a smooth experience:

  • Always use a virtual environment for your projects.
  • Use type hints for all your route parameters and return types. This improves code clarity and validation.
  • Organize your routes in separate modules for better maintainability.
  • Use environment variables for configuration. Esmerald works great with libraries like python-dotenv.
  • Write tests for your endpoints. Esmerald supports testing with httpx.

To test your app, you can use the TestClient from Starlette. Here is a quick example:


# test_app.py - Simple test for Esmerald app

from esmerald.testclient import EsmeraldTestClient
from app import app

client = EsmeraldTestClient(app)

def test_home():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, Esmerald!"}

Conclusion

Installing Esmerald framework in Python is straightforward. You created a virtual environment, installed the package, and built a working app. You also added multiple routes and learned about project structure.

Esmerald is a modern and fast framework. It helps you build reliable APIs with less code. Now you can start exploring its features like WebSockets, background tasks, and OpenAPI documentation.

Practice by building a small project. Try adding more routes, using path parameters, and returning different data types. The official Esmerald documentation is a great resource for advanced topics. Happy coding!

Related Tutorials:

Recent Tutorials: