imgcompress

---

What is ImgCompress?

ImgCompress is a self-hosted image app in a single Docker container, easy for everyone with no IT knowledge needed: set it up once on your own server, NAS or PC, then do everything in a modern web page, with no command line. It makes images smaller, converts 70+ formats (HEIC, PSD, SVG, PDF and more), lets you edit them (crop, exact sizes, text, logos, thumbnails), makes small images bigger and sharper with AI up to 16K, and removes backgrounds. The AI is already built in, and everything runs locally inside your container on your own hardware: private, no cloud APIs, works offline, free and open source.

---

Features

Feature	Details
70+ Image Formats	HEIC, HEIF, PSD, SVG, AVIF, EPS, PDF, WebP, TIFF, BMP, GIF, and 60 more (which are tested)
AI Background Removal	Built in and ready to use. No account, no subscription, no upload
AI Upscaling	Make small images bigger and sharper, up to 16K, offline (guide)
Image Editor	Crop, exact sizes, backgrounds, text and logos before converting (guide)
Bulk Compression	Make a whole folder of photos smaller in one go
Format Conversion	HEIC to WebP, PSD to JPG, SVG to PNG, image batches to paginated PDF, and more (WebP guide)
Web App + CLI	An easy web page for everyday use, plus a command line for automation
One Container	Everything is included. Nothing else to install
Works Offline	After the first download, no internet is needed, ever

What’s new in v1.0: the image editor, AI upscaling, SVG import, WebP export and more. See the release notes.

---

Image editor

Edit images right in the browser before you convert them. Everything is rendered on your own server.

• Crop, resize and rotate: pick an exact size, add a background, a logo or other pictures, and turn anything. Undo, keyboard shortcuts and touch on tablets included.
• YouTube thumbnails and social media sizes: presets for YouTube, Shorts and stories, Instagram, X, link previews, GitHub, Pinterest, Full HD, 2K and 4K.
• Add text to an image: titles, subtitles and watermarks with a choice of fonts, color, shadow and angle.
• Smart crop: resize to an exact size and keep the important part in frame, or keep the whole image on a blurred background.

---

AI image upscaling

Make small photos and drawings bigger and sharper, up to 16K. The AI is already built in: just switch it on. Pick General for photos or Anime for drawings, anime and logos. For General, pick the Image type: Photo (keep details) (the default) for sharp photos, Balanced for everyday images, or Old or noisy photo (smooth) for grainy ones. Same speed. It runs on your server’s CPU, so no graphics card is needed, and nothing is uploaded. Guide

Original vs. AI upscaled (Anime): the same spot at the same size. Left: the original, just enlarged. Right: AI upscaling (Anime), done by the AI built into ImgCompress, inside your own container. Nothing is uploaded, your images never leave your server.

Original	AI upscaled (Anime)

A tiny drawing (118 × 104 px) made 4x bigger. Left: normal enlargement. Right: AI upscaling (Anime), done by the AI built into ImgCompress, inside your own container. Nothing is uploaded, your images never leave your server. The second row zooms in on one fingernail.

Original	AI upscaled (Anime)

---

AI Background Removal: Local & Private

Remove the background from a photo in one click, without uploading it anywhere. The AI is already built in and runs on your own hardware, inside your container. No file ever leaves your server. Nothing to install, no account, no subscription.

Original	Background Removed

---

Quick Start

Copy this command, run it once, then open localhost:3001 in your browser. That’s it, about 60 seconds. You only need Docker.

docker run -d \
  --name imgcompress \
  -p 3001:5000 \
  karimz1/imgcompress:latest

Prefer Docker Compose? Ready-made configurations live in docker/compose/:

• advanced.docker-compose.yaml for use at home: open it from any device on your network. Safe defaults are already set.
• proxied.docker-compose.yaml for your own web address with HTTPS (uses Traefik and, if you like, free Let’s Encrypt certificates).

Step-by-step instructions for both are in the compose guide.

Home-lab example (Traefik + ntfy): a great starting point for self-hosters. Every self-hoster uses a different approach; this is one I find simple and easy to get started with. Traefik, ImgCompress and your own ntfy with .lan names — short steps and a diagram in docker/compose/homelab-traefik-ntfy/.

Each upload can be up to 40 GB. Cap it with -e MAX_UPLOAD_SIZE_MB=1024 (1 GB is a good public limit). Upload limit.

WEB_WORKERS defaults to auto (one per CPU). Lower it on small machines to save RAM, e.g. -e WEB_WORKERS=2. Web workers.

Set -e DISABLE_UPDATE_CHECK=true to stop the browser checking GitHub for new releases (version stays in the footer). Update check.

Notify me when done (optional): set NOTIFY_URL (e.g. NOTIFY_URL=ntfy://notify.lan/<topic>) plus optional PUBLIC_BASE_URL and TZ. A switch appears while a job runs; you get one message when it finishes, with a private result link if PUBLIC_BASE_URL is set. Full setup: Notify me when done. Ready-made compose: homelab-traefik-ntfy.

For more settings, such as hiding the mascot, see the full installation guide.

---

Why I Built ImgCompress

I was tired of the “software loop.” Every time I needed something simple, I had to install another app:

• PSD files: Needed specialized software just to convert them to an image file.
• HEIC files: Needed another converter for regular photo files.
• Image to PDF: Needed another app just to share a screenshot for work, since a PDF is often better for emails and easy for others to print.
• AI Backgrounds: I realized I needed one more app for that too.

I thought to myself: “Why can’t one tool just do it all?” Plus, uploading personal photos to random online converters never felt right to me.

One Toolbox for Everything

So I built a single toolbox that can take over 70 different formats and fix them all in one place. Whether you need to convert PSD or HEIC files to an image, turn a screenshot into a PDF for a work email, or shrink a massive 4K photo, this tool does it automatically.

The community has now pulled the image tens of thousands of times, which shows the pain is real.

Why Docker?

I chose Docker because it keeps your computer clean. Instead of installing 70 different tools yourself, you get one ready-to-go box called imgcompress that runs anywhere. It just works.

---

Privacy by Design

No cloud	Converting, compressing and the AI all run locally inside your container. Your images never leave your server.
No tracking	No analytics and no data sent home. After it starts, it stays quiet on the network.
Works offline	After the first download, it never needs the internet again. No license checks, no expiry.
Free and open source	GPL-3.0. Anyone can read the code, and you can use it for free, forever.

---

Security-Hardened Docker Image

ImgCompress keeps only what it needs, so there is less that can go wrong. For the technically curious, here are the details:

Minimal Surface	No shell (bash, sh), no network tools (curl, wget, etc.), no package manager. The attack surface is drastically reduced.
Minimal Components	System dependencies are aggressively pruned to maintain a minimal runtime environment.
Non-root User	Runs as a non-root user nonroot by default.
DHI Base Images	Using Docker Hardened Images from the official DHI project for build phases and runtime Image.
SBOM and Provenance	The Docker Image is built with a full Software Bill of Materials (SBOM) and build provenance attestation.

---

Multilingual Support

ImgCompress supports multiple frontend languages and welcomes community improvements to every locale. See the translation guide to add a new language, improve an existing translation, or get credited for meaningful language updates.

Supported languages:

• English
• Spanish
• Spanish (Mexico)
• Chinese (Simplified)
• Hindi
• Arabic
• French
• Portuguese (Brazil)
• Russian
• Japanese
• German
• Hungarian

---

Featured & Listed On

ImgCompress is recognized across the self-hosted community and featured on curated lists and deployment platforms:

• Awesome Self-Hosted : Community-curated index of self-hosted software.
• Coolify : Open-source PaaS — available as an official Coolify service.
• SelfHostedWorld & selfh.st: Featured directories and registries for self-hosting enthusiasts.
• xCloud: Offers one-click deployment of ImgCompress on a cloud server. ImgCompress itself is free — you only pay for the cloud server provided by xCloud. (I’m not affiliated with xCloud.)
• AlternativeTo & PitchHut: Listed as a privacy-respecting local image processing alternative.

A note from the creator:
A huge thank you to everyone who has supported ImgCompress and helped it reach more people! Seeing so many people embrace privacy-focused tools and use ImgCompress in their everyday workflows makes all the time and effort worthwhile. Thank you for being part of this journey! ❤️
— Karim Zouine, Creator of ImgCompress

Know another platform featuring ImgCompress, or want to add it? Get in touch.

---

Documentation

• Installation & Configuration: Docker setup, environment variables, reverse proxy examples
• Developer Guide: VS Code Dev Containers, architecture overview, local env setup
• imgcompress-chan (Bot): Custom helper bot that repairs Dependabot pnpm lockfiles and auto-merges dependency PRs
• E2E Testing with Playwright: How the app is tested end to end, offline
• Credits & Libraries: The open source projects that power ImgCompress
• Hall of Fame: Sponsors and contributors

---

Contributing

Contributions are welcome: bug reports, format requests, or pull requests.

• Read the Contributing Guide before opening a PR
• See the Architecture overview for how jobs, storage and cleanup fit together
• Browse good-first-issue labels for a starting point
• Every change runs a Playwright E2E suite; 49 of the 71 input formats pass automated conversion tests
• Maintainers: release workflow, build details and CI feature flags

---

Support the Project

ImgCompress is an independent open-source project built and maintained in my free time. If ImgCompress saves you time or server resources, consider supporting its continued development:

Donations are completely optional — starring the repo, sharing it, and contributing are already greatly appreciated!

---

License & Author

Author: Karim Zouine
License: GPL-3.0
Docker Image: hub.docker.com/r/karimz1/imgcompress

If ImgCompress saves you time, a GitHub star helps others discover it.