Iris Web Framework

Iris is a fast, batteries-included web framework for Go. It gives your next API or website expressive routing with typed path parameters, one place for error handling, dependency injection that keeps code testable, and production defaults that are secure out of the box.

Version 14 is the largest release in the project's history. The framework was rebuilt around Go generics: a compile-enforced application builder, typed request helpers that validate for you, controllers resolved by the dependency container, and an error pipeline you configure once. HISTORY.md records everything new; the Migration Guide brings v12 applications forward in one sitting.

🤖 Ask AI about Iris. Google's free Code Wiki for Iris is generated from this repository and stays in sync with it, commit by commit. Browse the architecture with diagrams, or ask its chat plain-language questions about the codebase and get answers grounded in the actual source. For an assistant that writes Iris code with you, Plexon AI, the desktop assistant built by the author of Iris, ships the Iris skill built in. The same skill installs into Claude Code as a plugin; see AI Tools for Iris below.

Learn what others say about Iris and star this open-source project to support its development. Curious about speed? See the server benchmarks.

package main

import "github.com/kataras/iris/v14"

func main() {
    app := iris.New()

    app.Get("/", func(ctx iris.Context) {
        ctx.JSON(iris.Map{"message": "Hello, World!"})
    })

    app.Get("/greet/{name:string}", func(ctx iris.Context) {
        ctx.WriteString("Hello, " + ctx.Params().GetString("name"))
    })

    app.Listen(":8080")
}

iris.NewBuilder().
    Prefix("/api").
    AllowOrigin("*").
    Compression(true).
    LogRequests(true).
    Health(true, "production", "kataras").
    Errors(errors.NewOptions().
        MapErrors(errors.NotFound, catalog.ErrNotFound)).
    Services(catalog.NewRepository, catalog.NewService).
    RouterMiddlewares().
    Middlewares().
    API("/products", api.NewProductsAPI).
    Build().
    Listen(":8080")

func (api *ProductsAPI) create(ctx iris.Context) {
    input, ok := ctx.BindJSON[catalog.ProductInput]()
    if !ok {
        return // 400 already written: malformed JSON or failed Validate.
    }

    id, err := api.svc.Create(ctx, input)
    ctx.Created(id, err) // 201, or the centrally mapped error.
}

As one Go developer once said, Iris got you covered all-round and standing strong over the years.

What you get with Iris v14:

• Routing with typed path parameters ({id:uuid}, {n:int}, {addr:email} and more), custom macros and constraints. Invalid input is rejected before your handler runs.
• iris.NewBuilder: CORS, compression, access logging, health endpoint, error mapping, services and API groups assembled in one compile-checked chain.
• Dependency injection: constructors declare what they need, the container provides it. Startup Initializer hooks, automatic shutdown closers.
• The rest helpers and one central error map: thin handlers, canonical machine-readable errors, internals never leak to clients.
• Request payloads that validate themselves: implement Validate() error and ctx.BindJSON runs it after decoding.
• Thirty-one built-in middleware: accesslog, API keys, basicauth, bodylimit, cache, CORS, hCaptcha and reCAPTCHA, JWT, monitor, pprof, rate limiting, recovery, request IDs, rewrite, sessions, versioning and more.
• Authentication at every scale: one-line Basic Auth, API keys, a generic JWT SDK, a complete identity server and an OAuth2 provider.
• MVC controllers built on Go generics.
• WebSockets, gRPC serving and API versioning.
• View engines: HTML, Django, Handlebars, Pug and more through iris-contrib/views.
• Localization with pluralization and language detection, plus sitemaps.
• Sessions with secure cookie defaults (Secure, SameSite=Lax out of the box).
• Rich responses: JSON, JSONP, XML, YAML, Markdown, Protocol Buffers, MessagePack, content negotiation, streaming and Server-Sent Events.
• AI backends: the ai package renders and relays streamed model output over HTTP (text deltas, reasoning traces, tool-call fragments, usage). It is provider-agnostic and ships no vendor SDK.
• An HTTP client, the client package, for calling other services under the same JSON rules the server side uses.
• Response compression: gzip, deflate, brotli, snappy, s2, zstd.
• TLS with Let's Encrypt, and ngrok tunneling, one blank import of core/server/ngrok away, to put a dev app on the internet in seconds.
• In-memory HTTP testing: full-application tests with no ports, no network and no sleeps.
• A complete book that is free to read online and to download, a hands-on tutorial and a live AI wiki (see Learning Iris below).
• And the most important: you get fast answers and support, from the first day until now.

With your help, we can improve Open Source web development for everyone!

New to Iris? Start with the Getting Started Tutorial: one document that takes you from go mod init to a tested, production-shaped REST API. Upgrading from v12? See the Migration Guide. Questions at any point? Ask the free live AI wiki at codewiki.google/github.com/kataras/iris. Google generates it from the Iris source and keeps it in sync, and its built-in chat answers questions about the codebase.

The only requirement is the Go Programming Language, version 1.27 or later.

$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/iris/v14@latest # or @v14.0.0

$ cd myapp
$ go get github.com/kataras/iris/v14@latest

$ go mod tidy
$ go run .

Iris contains extensive and thorough documentation making it easy to get started with the framework.

For a more detailed technical documentation you can head over to our godocs. For a complete, hands-on introduction to the recommended v14 stack read the Getting Started Tutorial, and if you are upgrading from v12 follow the Migration Guide.

Prefer learning from code? The 78 examples start with a thirteen-step tutorial that grows one service from a single route to a tested, production-shaped API, then cover every topic in the order the book teaches it: routing, controllers, requests, responses, middleware, dependency injection, errors, authentication, configuration, views, databases, websockets, testing, production and the framework's extension points. Every one of them was compiled and exercised over HTTP before it was committed.

A preface, 24 chapters and an epilogue, every code example verified against the framework source. Each chapter opens with a plain-language background for newcomers and closes with curated further reading. Every chapter is free to read online; the book page has the full table of contents.

The PDF is free too. Download it directly: there is no form to fill in and nothing to request. If the book helps you, sponsoring the project is how you take part in the development of Iris.

Two AI tools know this framework specifically, beyond what a general model knows about Go.

The live AI wiki is free and runs in your browser: browse the architecture, or ask its chat about the codebase.

Plexon AI is a desktop assistant for Windows, macOS and Linux, built by the author of Iris. It ships the Iris skill built in: the v14 API, the builder chain, the rest helpers, error mapping, the auth SDK and the testing patterns, in twenty-one reference documents the assistant loads on demand while it writes your code. Turn the skill on from the Skills panel, or install the Software Developer persona, which enables it together with the rest of its engineering tooling. Download Plexon AI.

This repository is also a plugin marketplace, so the CLI can install the same skill and update it in place:

$ claude plugin marketplace add kataras/iris
$ claude plugin install iris@kataras-iris

The same pair works as slash commands inside a session (/plugin marketplace add kataras/iris, then /plugin install iris@kataras-iris). Later:

$ claude plugin marketplace update kataras-iris   # pull newer versions
$ claude plugin details iris                      # what it contains and its token cost
$ claude plugin uninstall iris                     # remove it

--scope user is the default. Pass --scope project to record the install in the current project instead, so your team picks it up from your repository.

The plugin ships one skill and nothing else: no commands, no agents, no hooks, no MCP servers. Installing it cannot change how Claude Code behaves outside of Iris work.

To try a change from a checkout before installing it, point a session at the folder for that session only:

$ claude --plugin-dir /path/to/iris

Without the plugin machinery, copy the skill folder into your skills directory instead. Personal, available in every project:

$ npx degit kataras/iris/skill/iris ~/.claude/skills/iris

Project-scoped:

$ npx degit kataras/iris/skill/iris .claude/skills/iris

This route works for any assistant that reads Markdown instructions, not only Claude Code: point your agent configuration at skill/iris/SKILL.md, and it loads the reference document that matches the task at hand. It has no version tracking, which is the trade-off against the plugin install above.

We'd love to see your contribution to the Iris Web Framework! For more information about contributing to the Iris project please check the CONTRIBUTING.md file.

List of all Contributors

If you discover a security vulnerability within Iris, please send an e-mail to iris-go@outlook.com. All security vulnerabilities will be promptly addressed.

This project is licensed under the BSD 3-clause license, just like the Go project itself.

The project name "Iris" was inspired by the Greek mythology.