By UATeam in Immich —

How to Update Immich: A Step-by-Step Guide

Immich is a self-hosted media platform designed for managing and sharing photos and videos. Keeping Immich updated ensures access to the latest features, security patches, and performance improvements. This guide walks you through updating Immich safely and efficiently.

Why Update Immich?

Regular updates offer:

  1. New Features: Access to enhanced functionalities.
  2. Bug Fixes: Resolves issues in previous versions.
  3. Security Patches: Protects your media library from vulnerabilities.
  4. Performance Enhancements: Improves speed and efficiency.

Preparation Before Updating

  1. Backup Your Data:
    • Back up your database and media files to ensure data recovery in case of issues.
  2. Check Current Version:
    • Log in to your Immich instance and navigate to the settings or admin panel to find the current version.
  3. Read the Release Notes:

Example for Docker:

docker exec <database-container> pg_dumpall -U postgres > backup.sql

How to Update Immich

1. If Using Docker

Immich is commonly deployed using Docker, making updates straightforward.

Step 1: Pull the Latest Docker Images

Update the Immich Docker images to the latest version:

docker-compose pull

Step 2: Stop Running Containers

Stop the Immich containers before applying updates:

docker-compose down

Step 3: Start Containers with Updated Images

Restart the containers to apply the latest updates:

docker-compose up -d

Step 4: Verify the Update

  • Check the Immich admin panel to confirm the version.
  • Ensure all features are functioning correctly.

2. If Using a Manual Deployment

For manual installations (e.g., running on bare-metal servers), follow these steps:

Step 1: Backup the Application

  • Copy the existing application files to a backup directory.

Step 2: Pull the Latest Code

Navigate to the Immich installation directory and pull the latest changes:

git pull origin main

Step 3: Install Dependencies

Reinstall dependencies to ensure compatibility:

npm install

Step 4: Restart the Server

Restart the Immich service to apply updates:

pm2 restart immich

3. Update Environment Variables

  • Check the release notes for any changes in .env configuration.
  • Update the .env file with new variables if necessary, and restart Immich.

Post-Update Checklist

  1. Verify Data Integrity:
    • Ensure your media files and database are intact.
  2. Test Core Features:
    • Upload, view, and share media to confirm that the update was successful.
  3. Monitor Logs:
  5. Remove Old Images:

Clean up unused Docker images to save storage:

docker image prune -f

Check Docker or system logs for any errors:

docker logs <container-name>

Troubleshooting Common Issues

1. Update Fails or Crashes

  • Solution: Roll back to the previous version using your backup and retry the update.

2. Missing Dependencies

  • Solution: Ensure all required dependencies are installed as per the updated documentation.

3. Features Not Working

  • Solution: Verify your .env configuration and ensure it matches the latest requirements.

4. Database Issues

Solution: Migrate the database schema if needed:

docker exec <container-name> npm run migrate

Best Practices for Updating Immich

  1. Update Regularly:
    • Stay current with the latest releases to avoid accumulating technical debt.
  2. Test in a Staging Environment:
    • Deploy updates on a test server before applying them to production.
  3. Monitor Community Forums:
    • Engage with the Immich community for tips and troubleshooting.

Conclusion

Updating Immich is a straightforward process, whether you use Docker or manual deployment. By following the steps in this guide, you can ensure a smooth transition to the latest version while safeguarding your media library. Regular updates not only enhance functionality but also keep your instance secure and efficient.