---
title: How to upgrade a self-hosted Langfuse deployment
description: Use this guide to keep your Langfuse deployment up to date. Updates between minor/patch versions can be applied automatically. For major versions, please refer to the migration guides.
label: "Version: v4"
sidebarTitle: "How to Upgrade"
---

# Upgrading a Self-Hosted Langfuse Deployment

Langfuse evolves quickly ([changelog](/changelog)) and keeping your deployment up to date is key to benefit from security, performance, and feature updates.

The Langfuse versioning and upgrade process is optimized for minimal complexity and disruption. If you ever experience any issues, please create an [issue on GitHub](/issues) or contact the maintainers ([support](/support)).

## How to upgrade

It is recommended to be familiar with our [versioning](/self-hosting/upgrade/versioning) policy before upgrading existing deployments.

### Minor/Patch Versions

Updates within a major version are designed to be non-disruptive and are automatically applied. On start of the application, all migrations are automatically applied to the databases.

You can automatically use the latest version of a major release by using `langfuse/langfuse:4` and `langfuse/langfuse-worker:4` as the image tags in your deployment.

To update deployments, follow the update section in our deployment guides:

- [Local](/self-hosting/deployment/docker-compose#how-to-upgrade)
- [VM](/self-hosting/deployment/docker-compose#how-to-upgrade)
- [Docker](/self-hosting/deployment/docker-compose#how-to-upgrade)
- [Kubernetes (Helm)](/self-hosting/deployment/kubernetes-helm#how-to-upgrade)

### Major Versions

If you upgrade between major versions, please follow our migration guides:

- [v3.x.x to v4.x.x](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4)
- [v2.x.x to v3.x.x](/self-hosting/upgrade/upgrade-guides/upgrade-v2-to-v3)
- [v1.x.x to v2.x.x](/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2)

The [Langfuse Helm chart](/self-hosting/deployment/kubernetes-helm) is versioned independently of the Langfuse server and has its own major versions. If you run the chart with bundled data stores, [upgrade the chart from v1 to v2](/self-hosting/deployment/kubernetes-helm#chart-v1-to-v2) before you upgrade Langfuse to v4: the v1 chart cannot bring its bundled ClickHouse to a v4-compatible version.

## Release Notes

**[Langfuse OSS updates](/self-hosting/oss-newsletter)** — get an email when we ship important features and new releases for self-hosted (open source) Langfuse. Self-hosting updates only, no spam.

Subscribe to the Langfuse OSS newsletter at https://langfuse.com/self-hosting/oss-newsletter.

You can also watch the [GitHub releases](https://github.com/langfuse/langfuse/releases) for information about the changes in each version.

<span>_Watch the repository on GitHub to get notified about new releases_</span>

## Support

If you experience any issues, please create an [issue on GitHub](/issues) or consider other [support options](/support) as part of our Enterprise offering.

Alternatively, you may consider using [Langfuse Cloud](/docs/deployment/cloud), which is a fully managed version of Langfuse. If you have questions, learn more about its security and privacy [here](/security).

---

If you experience any issues when self-hosting Langfuse, please:

1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page.
2. Use [Ask AI](/ask-ai) to get instant answers to your questions.
3. Ask the maintainers on [GitHub Discussions](/gh-support).
4. Create a bug report or feature request on [GitHub](/issues).

  Enterprise-grade support is available when self-hosting Langfuse. Learn more on
  our [pricing page](/pricing-self-host).

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/self-hosting/upgrade.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.