This is documentation for the next version of Grafana Pyroscope documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Pyroscopebreadcrumb arrow Release notesbreadcrumb arrow V2.0
Open source

Version 2.0.0 release notes

The Pyroscope team is excited to present Grafana Pyroscope 2.0.0.

Pyroscope 2.0 makes the v2 storage architecture (segment-writer, query-backend, metastore, compaction-worker) the default for OSS users. v2 writes profiles directly to object storage and removes the need for in-memory ingesters, simplifying operations and reducing resource usage at scale. v1 remains available via an opt-in flag so existing deployments can upgrade without data loss.

This release contains breaking changes. Review the v1 to v2 migration guide before upgrading.

Notable changes are listed below. For the full diff, check out the 2.0.0 changelog.

Breaking changes

  • Go module path bumped to github.com/grafana/pyroscope/v2. Library consumers must update their imports (#5073)
  • Default write path flipped from ingester to segment-writer. Set -write-path=ingester to preserve v1 behavior (#5038)
  • Default storage backend flipped from empty to filesystem (#5038)
  • New -architecture.storage flag (v1 | v1-v2-dual | v2), default v1-v2-dual (#5038)
  • Error at startup when -architecture.storage includes v2 and no object-storage backend is configured (#5074)
  • Default filesystem paths moved under ./data/v2/ (#5038)
  • Removed PYROSCOPE_V2_EXPERIMENTAL environment variable (#5038)
  • Removed legacy positional server argument from the pyroscope binary (#5038)
  • Label sanitization disabled by default; UTF-8 label names with dots are accepted as-is. Set -validation.disable-label-sanitization=false to restore previous behavior (#5038)
  • Helm chart 2.0.0 replaces all.enable-v1-write-path / all.enable-v1-read-path with architecture.storage, removes persistence.shared and migration.queryBackend, and forwards ingesterWeight / segmentWriterWeight correctly (#5076)

Enhancements

  • profilecli: Add debuginfo upload subcommand (#5080)

Fixes

  • Fix missed v1 import path in pyroscope_test.go after module bump to v2 (#5077)
  • make: Add frontend/build dependency to reference-help target (#5071)

Documentation

  • Improve v1 → v2 migration docs: switch to --reset-then-reuse-values, target chart 2.0.0 (#5079)
  • Add v1.21 release notes (#5082)
  • Fix contributors grid layout in README (#5078)

Upgrade

To upgrade from v1.21.x:

  1. Read the v1 to v2 migration guide.
  2. If you import Pyroscope as a Go library, update imports to github.com/grafana/pyroscope/v2.
  3. If you deploy with Helm, upgrade to chart 2.0.0 and review the removed and renamed values listed above.
  4. If you run the binary directly and want to stay on v1 storage, set -architecture.storage=v1 and -write-path=ingester explicitly — the previous defaults no longer apply.
  5. If you want to move to v2, configure object storage and set -architecture.storage=v2 (or leave v1-v2-dual during the transition).