Phockup

Phockup (in case this link dissapears I also forked it in my repository) is photo backup, a useful command line tool to organize your pictures. In this post we’ll show how to isntall and use it. The software seems to be a bit old and not updated but it just works.

Install Phockup

In MacOS the easiest would be installing using brew with

brew tap ivandokov/homebrew-contrib
brew install phockup

but this doesn’t work, it seems to install but correctly when you type phockup you get a message of missing packages (the famous tqdm in this case):

Traceback (most recent call last):
  File "/usr/local/bin/phockup", line 11, in <module>
    from src.phockup import Phockup
  File "/usr/local/Cellar/phockup/1.13.0/src/phockup.py", line 11, in <module>
    from tqdm import tqdm
ModuleNotFoundError: No module named 'tqdm'

We need to install the dependencies, we will do it by clonning phockup repository and creating a virtual environment in it, then install the requirements.txt. First clone the repository:

mkdir -p ~/.venvs
git clone git@github.com:ivandokov/phockup.git ~/.venvs/phockup

And select a recent python version

pyenv install 3.12
pyenv shell 3.12

Then create the environment in the clonned repository

python -m venv ~/.venvs/phockup/.venv

And install the requirements in the environment

source ~/.venvs/phockup/.venv/bin/activate

python -m pip install --upgrade pip
pip install -r ~/.venvs/phockup/requirements.txt
deactivate

if you want to execute phockup just activate the environment and run phockup installed from brew.

source ~/.venvs/phockup/.venv/bin/activate
phockup --help

See that we didn’t install any extra CLI (there’s no phockup binary in bin directory in the environment). Check with which phockup and you will get it in /usr/local/bin/phockup.

I know, weird installation but the brew tap is broken as of now and as I mentioned the project doesn’t seem to be maintained anymore so we had to be a little hacky here.

Run phockup

In general you can run phockup with the commands

source ~/.venvs/phockup/.venv/bin/activate
phockup --help

Let’s run phockup to backup our images and movies. We have a folder of pictures and movies that we want to organise ${SOURCE} and a place we want to save the pictures to ${DESTINATION}. This last folder may be empty or with other pictures already.

source ~/.venvs/phockup/.venv/bin/activate

# the source (where movies and photos are) and empthy destination
SOURCE=~/Downloads/new_pictures
DESTINATION=~/Downloads/organised_new_pictures

# assuming we haven't created the new destination directory
mkdir -p ${DESTINATION}

Now start the process by running

phockup ${SOURCE} ${DESTINATION} \
    --progress \
    -d YYYY.MM  \
    --date-field "DateTimeOriginal CreateDate FileModifyDate"

Practical case: Backup photos from Android phone

I downloaded pictures from my phone using adb (install with brew install android-platform-tools), a command line tool that allows you interact with your android device from terminal. Once installed and before plugging your phone into the USB port you need to enable deloper (go to Settings -> About phone -> Build number and tap 7 times to Build number). Then enable USB debugging (go to Settings > System > Developer options, scroll down and activate Enable USB debugging option). Finally plug the phone to your USB and you will see a popup on your phone asking “Allow USB Debugging?” with a figerprint code, just enable and you will be good to go for the next step.

Let’s ssh to the device by running adb shell and then go the camera directory and display the pictures there.

adb shell
cd /sdcard/DCIM/Camera
ls

Let’s open another terminal and pull the data to our computer

# camera pictures
SOURCE=${HOME}/Downloads/PixelPhotos
adb pull /sdcard/DCIM/Camera ${SOURCE}

# WhatsApp images
SOURCE=${HOME}/Downloads/WhatsappImages
adb pull "/sdcard/Android/media/com.whatsapp/WhatsApp/Media/WhatsApp Images/" ${SOURCE}

mv ${SOURCE}/Private/* ${SOURCE}/
mv ${SOURCE}/Sent/* ${SOURCE}/

rm -rf ${SOURCE}/Private/
rm -rf ${SOURCE}/Sent/

# WhatsApp video
SOURCE=${HOME}/Downloads/WhatsappVideo
adb pull "/sdcard/Android/media/com.whatsapp/WhatsApp/Media/WhatsApp Video/" ${SOURCE}

mv ${SOURCE}/Private/* ${SOURCE}/
mv ${SOURCE}/Sent/* ${SOURCE}/

rm -rf ${SOURCE}/Private/
rm -rf ${SOURCE}/Sent/

# and consolidate all photos and videos to PixelPhotos
SOURCE=${HOME}/Downloads/WhatsappImages
mv ${SOURCE}/* ${HOME}/Downloads/PixelPhotos
rm -rf ${SOURCE}

SOURCE=${HOME}/Downloads/WhatsappVideo
mv ${SOURCE}/* ${HOME}/Downloads/PixelPhotos
rm -rf ${SOURCE}

SOURCE=${HOME}/Downloads/WhatsappVideo
mv ${SOURCE}/* ${HOME}/Downloads/PixelPhotos
rm -rf ${SOURCE}

Now define the destination and copy all files while changing their names with phockup.

SOURCE=${HOME}/Downloads/PixelPhotos
DESTINATION=${HOME}/Downloads/organized_PixelPhotos
mkdir -p ${DESTINATION}

source ~/.venvs/phockup/.venv/bin/activate
phockup ${SOURCE} ${DESTINATION} \
    --progress \
    -d YYYY.MM  \
    --date-field "DateTimeOriginal CreateDate FileModifyDate"

Where --progress indicates we want to see the progress bar (powered by tqdm that we were missing), -d is the format. The last parameter --date-field is to use the image metadata through exiftool to get the metadata (including date). If we run ls -lhat ~/Downloads/organized_PixelPhotos we will see the directory structure:

drwxr-xr-x sebas staff 151 KB Tue Jul 29 00:58:20 2025  2025.07
drwxr-xr-x sebas staff 3.9 KB Tue Jul 29 00:58:06 2025  2024.12
drwxr-xr-x sebas staff 2.8 KB Tue Jul 29 00:57:58 2025  2024.11
drwxr-xr-x sebas staff 6.0 KB Tue Jul 29 00:57:49 2025  2024.10
drwxr-xr-x sebas staff 6.5 KB Tue Jul 29 00:57:14 2025  2024.08
drwxr-xr-x sebas staff 6.3 KB Tue Jul 29 00:56:27 2025  2025.06
drwxr-xr-x sebas staff 2.7 KB Tue Jul 29 00:55:34 2025  2025.05
drwxr-xr-x sebas staff 2.3 KB Tue Jul 29 00:55:05 2025  2025.04
drwxr-xr-x sebas staff  10 KB Tue Jul 29 00:54:39 2025  2025.03
drwxr-xr-x sebas staff 1.2 KB Tue Jul 29 00:52:36 2025  2025.02
drwxr-xr-x sebas staff 896 B  Tue Jul 29 00:52:22 2025  .
drwxr-xr-x sebas staff 5.0 KB Tue Jul 29 00:52:21 2025  2025.01
drwxr-xr-x sebas staff 4.4 KB Tue Jul 29 00:48:02 2025  2024.09
drwxr-xr-x sebas staff  10 KB Tue Jul 29 00:46:01 2025  2024.07
drwxr-xr-x sebas staff 3.3 KB Tue Jul 29 00:44:43 2025  2024.06
drwxr-xr-x sebas staff 2.3 KB Tue Jul 29 00:44:18 2025  2024.05
drwxr-xr-x sebas staff 2.1 KB Tue Jul 29 00:44:01 2025  2024.04
drwxr-xr-x sebas staff 4.6 KB Tue Jul 29 00:43:44 2025  2024.03
drwxr-xr-x sebas staff 8.1 KB Tue Jul 29 00:43:05 2025  2024.02
drwxr-xr-x sebas staff 2.4 KB Tue Jul 29 00:41:35 2025  2024.01
drwxr-xr-x sebas staff 2.9 KB Tue Jul 29 00:41:00 2025  2023.12
drwxr-xr-x sebas staff 2.9 KB Tue Jul 29 00:40:25 2025  2023.11
drwxr-xr-x sebas staff 3.1 KB Tue Jul 29 00:40:01 2025  2023.10
drwxr-xr-x sebas staff 2.8 KB Tue Jul 29 00:39:29 2025  2023.09
drwxr-xr-x sebas staff  11 KB Tue Jul 29 00:39:05 2025  2023.08
drwxr-xr-x sebas staff 1.8 KB Tue Jul 29 00:37:39 2025  2023.07
drwx------ sebas staff 6.9 KB Tue Jul 29 00:25:32 2025  ..

Where the format is YYYY.MM, then if we inspect the filenames we see something like 20250317-132507.jpg, that’s a photo taken March the 17th at 13h, 25m and 07 seconds.

Closing remarks

Once you have your photo backup it is best if you can create a VeraCrypt volume and store your photos encrypted, then you can save to an external drive and a cloud service. Check out my Veracrypt Guide.