Successfully ran the Db2 Community Edition image on MBP M3

I had been trying to get this working for over a month, spending time every weekend researching it, but no matter what I did, I just couldn’t get it to run.

At first, I followed the official documentation (https://www.ibm.com/docs/en/db2/12.1.x?topic=system-macos), but during the container startup process—whether in an ARM or x86 environment—I kept running into numerous path-permission errors. In the end, the Db2 Community Edition image simply couldn’t start properly.

During that time, I looked up a lot of information online. Some users abroad even suggested running it with Lima and Podman. I did manage to get it to start properly at one point, but since I couldn’t reliably stop and restart the container, I eventually gave up…

Recently, I finally managed to start the Db2 Community Edition image using podman successfully with the following command:

podman run -h db2server --name db2server --detach --privileged=true \
-p 50000:50000 --env-file .env_list -v /Users/marksu/db2-container:/database icr.io/db2_community/db2

At first, I thought the success was due to the Db2 Community Edition image being updated to version 12.1.3.0. I originally suspected that version 12.1.2.0 had issues, so I went back and tested 12.1.2.0 again — and it also started successfully. That made me suspect the real problem was probably the macOS version or the Podman version.

Right now, the above command can successfully start the Db2 Community Edition image on a macOS 26.1 + Podman 5.7.0 setup. However, the command differs slightly from what’s written in the official documentation, so here are the details:

First, I created a directory named db2-container under /Users/marksu, and inside that directory I created a file called .env_list with the following content:

LICENSE=accept
DB2INSTANCE=db2inst1
DB2INST1_PASSWORD=password
DBNAME=testdb
BLU=false
ENABLE_ORACLE_COMPATIBILITY=false
UPDATEAVAIL=NO
TO_CREATE_SAMPLEDB=false
REPODB=false
IS_OSXFS=true
PERSISTENT_HOME=false
HADR_ENABLED=false
ETCD_ENDPOINT=
ETCD_USERNAME=
ETCD_PASSWORD=

The main difference from the official documentation is that I set PERSISTENT_HOME to false. Although the documentation states that this setting defaults to true and should only be changed to false when running with Docker on Windows.

However, based on my actual testing, if PERSISTENT_HOME is set to true, the Db2 Community Edition image starts without any issues the first time. But once you stop the Db2 container and try to start it again, errors occur and it fails to start properly. After switching PERSISTENT_HOME to false, this problem no longer occurs.

Using the “IBM DB2 Support” VS Code extension from Extension Studio, I was able to successfully connect to the testdb database inside the Db2 Community Edition image. IBM’s official “Db2 Connect” VS Code extension hasn’t been updated for a year and doesn’t support ARM-based macOS, so it’s not usable in this case.