Skip to main content

​
Overview

Regular updates ensure you have the latest features, performance improvements, and security patches. Umami follows semantic versioning (MAJOR.MINOR.PATCH).
Current version information is available in package.json and displayed in the Umami interface.

​
Version Information

Check your current version:
Look in the bottom left corner of the Umami dashboard after logging in.

​
Release Types

Version TypeExampleChangesRisk
Major3.0.0Breaking changes, major featuresHigh
Minor3.1.0New features, backward compatibleLow
Patch3.0.1Bug fixes, security patchesVery Low
Always backup your database before upgrading, especially for major version updates.

​
Upgrading Docker Installation

1

Backup database

Create a backup before upgrading:
# PostgreSQL backup
docker compose exec db pg_dump -U umami umami > backup-$(date +%Y%m%d).sql

# Compressed backup
docker compose exec db pg_dump -U umami umami | gzip > backup-$(date +%Y%m%d).sql.gz
2

Pull latest image

docker compose pull umami
This downloads the latest image without stopping the current container.
3

Recreate container

docker compose up -d --force-recreate umami
This:
  • Stops the current container
  • Creates a new container with the latest image
  • Runs database migrations automatically
  • Starts the new container
4

Verify upgrade

# Check container is running
docker compose ps

# View logs for errors
docker compose logs -f umami

# Access Umami and verify version

​
One-Line Update

Combine steps for quick updates: 
docker compose pull && docker compose up --force-recreate -d

​
Specific Version

Upgrade to a specific version:
docker-compose.yml
services:
  umami:
    image: ghcr.io/umami-software/umami:v3.0.3  # Specific version
    # or
    image: ghcr.io/umami-software/umami:latest  # Latest version
Then: 
docker compose up -d --force-recreate

​
Rollback

If something goes wrong, rollback to previous version: 
# Change image tag in docker-compose.yml
image: ghcr.io/umami-software/umami:v3.0.2

# Recreate container
docker compose up -d --force-recreate

# Or restore database backup
docker compose exec -T db psql -U umami umami < backup-20260303.sql

​
Upgrading Source Installation

​
Standard Upgrade Process

1

Backup database

# PostgreSQL
pg_dump -U umami umami > backup-$(date +%Y%m%d).sql

# Compressed
pg_dump -U umami -Fc umami > backup-$(date +%Y%m%d).dump
2

Stop application

# If using pm2
pm2 stop umami

# If using systemd
sudo systemctl stop umami

# Or just Ctrl+C if running in terminal
3

Pull latest code

cd /path/to/umami
git pull origin master
Or for a specific version:
git fetch --tags
git checkout v3.0.3
4

Install dependencies

pnpm install
This updates dependencies to versions specified in the new release.
5

Run build

pnpm build
The build process:
  • Generates Prisma client
  • Runs database migrations
  • Builds the Next.js application
  • Updates tracker script
6

Start application

pnpm start

# Or with pm2
pm2 start umami

# Or with systemd
sudo systemctl start umami

​
Quick Update Command

Combine all steps: 
cd /path/to/umami && \
  git pull && \
  pnpm install && \
  pnpm build && \
  pnpm start

​
Using a Script

Create an update script:
update.sh
#!/bin/bash
set -e

echo "Backing up database..."
pg_dump -U umami umami > backup-$(date +%Y%m%d).sql

echo "Stopping Umami..."
pm2 stop umami

echo "Updating code..."
cd /path/to/umami
git pull

echo "Installing dependencies..."
pnpm install

echo "Building application..."
pnpm build

echo "Starting Umami..."
pm2 start umami

echo "Upgrade complete!"
pm2 logs umami
Make it executable and run: 
chmod +x update.sh
./update.sh

​
Kubernetes Upgrade

​
Update Deployment

1

Update image tag

Edit your deployment manifest:
umami-deployment.yaml
spec:
  containers:
  - name: umami
    image: ghcr.io/umami-software/umami:v3.0.3  # Update version
2

Apply changes

kubectl apply -f umami-deployment.yaml
Kubernetes will perform a rolling update.
3

Monitor rollout

# Watch rollout status
kubectl rollout status deployment/umami -n umami

# View pods
kubectl get pods -n umami -w

​
Using kubectl set image

Direct image update: 
kubectl set image deployment/umami umami=ghcr.io/umami-software/umami:v3.0.3 -n umami

​
Rollback Kubernetes Deployment

# View rollout history
kubectl rollout history deployment/umami -n umami

# Rollback to previous version
kubectl rollout undo deployment/umami -n umami

# Rollback to specific revision
kubectl rollout undo deployment/umami --to-revision=2 -n umami

​
Database Migrations

Migrations run automatically during the upgrade process:

​
Automatic Migration

Migrations run automatically on container start via the start-docker script:
npm-run-all check-db update-tracker start-server
The check-db script runs prisma migrate deploy.

​
Manual Migration

Run migrations manually if needed: 
# Check migration status
pnpm prisma migrate status

# Apply pending migrations
pnpm prisma migrate deploy

# Regenerate Prisma client
pnpm prisma generate

​
Skip Migration

Skip automatic migration: 
SKIP_DB_MIGRATION=1 pnpm start
Only skip migrations if you’re managing schema manually. Running with outdated schema will cause errors.

​
Version-Specific Upgrade Notes

​
Upgrading to v3.x

Breaking Changes:
  • Requires Node.js 18.18+
  • Requires PostgreSQL 12.14+
  • New database schema with additional tables
  • Updated API endpoints
New Features:
  • Team collaboration
  • Revenue tracking
  • URL shortener
  • Tracking pixels
  • Enhanced reporting
Migration Notes:
  • Allow extra time for migration (large databases may take 10+ minutes)
  • Default admin password changed to umami (was admin)
  • Review team permissions after upgrade

​
Upgrading from v2.x

1

Check Node.js version

node --version  # Must be 18.18+
Upgrade if needed:
nvm install 18
nvm use 18
2

Check PostgreSQL version

SELECT version();
Must be 12.14+. Upgrade PostgreSQL if needed.
3

Backup database

Critical for major version upgrades:
pg_dump -U umami -Fc umami > backup-pre-v3-$(date +%Y%m%d).dump
4

Perform upgrade

Follow standard upgrade process above.

​
Automated Updates

​
Renovate Bot

Use Renovate for automatic dependency updates:
renovate.json
{
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchPackageNames": ["ghcr.io/umami-software/umami"],
      "schedule": ["before 6am on monday"],
      "automerge": false
    }
  ]
}

​
Watchtower (Docker)

Automatic Docker container updates:
docker-compose.yml
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_SCHEDULE: "0 0 2 * * *"  # Daily at 2 AM
      WATCHTOWER_CLEANUP: "true"
    restart: always
Automatic updates can cause unexpected downtime. Use with caution in production.

​
Monitoring Updates

​
GitHub Releases

Watch for new releases:
  1. Visit GitHub Releases
  2. Click “Watch” → “Custom” → “Releases”
  3. Get notified of new versions

​
RSS Feed

Subscribe to release feed: 
https://github.com/umami-software/umami/releases.atom

​
Changelog

Review changes before upgrading:
  • GitHub Changelog
  • Release notes include:
    • New features
    • Bug fixes
    • Breaking changes
    • Migration notes

​
Upgrade Checklist

  • Review changelog for breaking changes
  • Backup database
  • Check disk space (build requires temporary space)
  • Test upgrade in staging environment
  • Schedule maintenance window
  • Notify users of potential downtime
  • Verify Node.js and PostgreSQL versions
  • Have rollback plan ready
  • Monitor upgrade logs
  • Watch for migration errors
  • Check database performance
  • Verify application starts successfully
  • Verify version number in UI
  • Test core functionality (login, analytics, reports)
  • Check for JavaScript errors in browser console
  • Review application logs
  • Monitor performance metrics
  • Test data collection (tracker)
  • Verify API endpoints
  • Keep backup until stability confirmed

​
Troubleshooting Upgrades

Check migration status:
pnpm prisma migrate status
View error details in logs:
docker compose logs umami
Common issues:
  • Insufficient disk space
  • Database connection timeout
  • Constraint violations from existing data
Rollback if needed:
# Restore from backup
pg_restore -U umami -d umami -c backup.dump
Check logs for errors:
# Docker
docker compose logs umami

# Source
pnpm start
Common issues:
  • Missing environment variables
  • Database connection failed
  • Port already in use
  • Node.js version mismatch
Verify environment:
node --version
echo $DATABASE_URL
Update tracker cache:
# The update-tracker script runs automatically
# Or run manually:
pnpm update-tracker
Clear browser cache and test:
# Check tracker loads
curl https://your-domain.com/script.js
Run database maintenance:
VACUUM ANALYZE;
REINDEX DATABASE umami;
Check for missing indexes:
pnpm prisma migrate status
Monitor query performance:
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

​
Best Practices

Test First

Always test upgrades in staging before production.

Backup Everything

Create backups before every upgrade, no exceptions.

Read Changelogs

Review release notes for breaking changes.

Monitor After Upgrade

Watch logs and metrics for issues after upgrading.

​
Next Steps

Migrations

Learn about database migrations

Troubleshooting

Solve upgrade issues

Environment Variables

Configure your instance

Docker Deployment

Docker upgrade details

Build docs developers (and LLMs) love

Get started for freeTalk to us