GPHOTO2(1)

📦
version 2.5.32 · 5 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable

🌸 GPHOTO2(1) 🌸 — straight outta The gPhoto2 Reference (the man)

okay bestie, buckle up, because this is the manual page for gphoto2, and it's a whole personality. it's long, it's got range, it's giving "reference document that ate." we're doing this together, one section at a time, and nothing gets skipped. not one flag. not one default value. periodt. 💅

✨ NAME ✨

gphoto2 — the command-line gphoto2 client. that's it, that's the name, short and iconic.

🦋 SYNOPSIS 🦋

like, here's the whole shape of it. yes it's a lot. no we're not scared.

gphoto2 [--debug] [--debug-logfile FILENAME] [--debug-loglevel LEVEL]
        [[-q] | [--quiet]] [[-v] | [--verbose]] [[-h] | [--help]]
        [--usage]
        [--hook-script FILENAME]
        [--list-cameras] [--list-ports] [--stdout] [--stdout-size]
        [--parsable]
        [--auto-detect] [--port PATH] [--speed SPEED] [--camera MODEL]
        [--filename FILENAME] [--filenumber FILENUMBER]
        [--usbid USBIDS]
        [[-a] | [--abilities]]
        [[--folder FOLDER] | [-f FOLDER]] [[[-R] | [--recurse]] |
        [--no-recurse]]
        [[-l] | [--list-folders]]
        [[-L] | [--list-files]] [[-m NAME] | [--mkdir NAME]]
        [[-r NAME] | [--rmdir NAME]] [[-n] | [--num-files]]
        [[-p RANGE or NAME] | [--get-file RANGE or NAME]] [[-P] |
        [--get-all-files]]
        [[-t RANGE or NAME] | [--get-thumbnail RANGE or NAME]]
        [[-T] | [--get-all-thumbnails]]
        [--get-raw-data RANGE or NAME] [--get-all-raw-data]
        [--get-audio-data RANGE or NAME] [--get-all-audio-data]
        [--get-exif RANGE or NAME] [--get-all-exif]
        [--get-metadata RANGE or NAME] [--get-all-metadata]
        [--upload-metadata FILENAME]
        [--force-overwrite]
        [--new]
        [[-d RANGE or NAME] | [--delete-file RANGE or NAME]] [[-D] |
        [--delete-all-files]]
        [[-u FILENAME] | [--upload-file FILENAME]] [--config]
        [--list-config] [--list-all-config]
        [--get-config CONFIGENTRY]
        [--set-config CONFIGENTRY=CONFIGVALUE]
        [--set-config-index CONFIGENTRY=CONFIGINDEX]
        [--set-config-value CONFIGENTRY=CONFIGVALUE] [--reset]
        [--capture-preview] [--show-preview]
        [[-F COUNT] | [--frames COUNT]] [[-I SECONDS] |
        [--interval SECONDS]]
        [--reset-interval]
        [--capture-image] [--trigger-capture]
        [--capture-movie SECONDS or COUNT] [--capture-sound]
        [--capture-tethered SECONDS, COUNT or STRING]
        [--wait-event SECONDS, COUNT or STRING]
        [--wait-event-and-download SECONDS, COUNT or STRING]
        [--keep] [--no-keep]
        [--reverse]
        [--show-info RANGE or NAME]
        [--show-exif RANGE or NAME]
        [--storage-info]
        [--summary]
        [--manual]
        [--about]
        [--shell]

💖 DESCRIPTION 💖

so the lore is: libgphoto2(3) is a cross-platform digital camera library, and gphoto2(1) is a command-line client for it. like the library is the main character and gphoto2 is her very capable bestie who handles the talking. 👑

real talk though, here's the one thing you gotta internalize before we go anywhere:

when an option takes a RANGE of files, thumbnails, or other data, they are numbered beginning at 1. a range is a comma-separated list of numbers or spans (first-last). and ranges are XOR (exclusive or), so that 1-5,3,7 is equivalent to 1,2,4,5,7. yeah. it's XOR. it ate and left no crumbs. write it down. 🫶

🎀 the options, in order, all of them, no cap 🎀

  • --debug — turn on debugging output. debug output goes to stderr by default, or to whatever filename you handed to the --debug-logfile option.
  • --debug-logfile FILENAME (since 2.3.0) — the logfile to write the debugging info to, if --debug is given.
  • --debug-loglevel LEVEL (since 2.5.5) — how chatty the debug logging gets. possible values, with incrementing verbosity, are: error, debug, data, all. the default is all.
  • --hook-script FILENAME (new after 2.3.0) — run the hook script FILENAME every single time a certain event happens within gphoto2. the hook script reads the environment variable ACTION, and it must ignore ACTION values it doesn't know about. like, mind your business, script.
    • ACTION=init — gphoto2 has just been initialized. if the hook script returns with a non-zero exit code right now, gphoto2 will abort. so like… be chill.
    • ACTION=start — gphoto2 has just finished parsing the command line and is about to start executing the commands given on the command line.
    • ACTION=download — gphoto2 has just downloaded a file to the computer, storing it in the file indicated by the environment variable ARGUMENT.
    • ACTION=stop — gphoto2 is about to finish. do your final cleanups here, bestie.

all other environment variables are passed to the hook script unchanged — and yes you can absolutely use that to pass data to the hook script. sneaky but valid.

the hook script may be specified in the ~/.gphoto/settings file as gphoto2=hook-script=filename.

  • -q, --quiet — quiet output (default=verbose). shhh. 🤫
  • -v, --version — display version and exit. that's the tea, bye.
  • -h, --help — display options and short description.
  • --usage — display a short usage message. the tl;dr of the tl;dr.
  • --list-cameras — list supported camera models.
  • --list-ports — list supported port devices.
  • --stdout — send file to stdout.
  • --stdout-size — print filesize before data.
  • --parsable — outputs the filelist in a line based format that could be passed into a shellscript or other filter. very pipeline-friendly of her.
  • --auto-detect — list auto-detected cameras and the ports to which they are connected.
  • --port PATH — specify port device. --list-ports prints a list of valid, usable ports. in case of multiple USB cameras, --auto-detect shows you the specific port each camera is connected to. 🦋
  • --speed SPEED — specify serial transfer speed.
  • --camera MODEL — specify camera model. the --list-cameras option prints a list of all explicitly supported cameras.

most model names contain spaces: remember to enclose the name in quotes so that the shell knows it is one parameter. for example:

--camera "Kodak DC240"
⚠️ note that if you specify --camera, you must also specify --port. otherwise the --camera option will be silently ignored. silently!! like it's not gonna warn you, it's just gonna ghost your whole setting. 😭
  • --filename FILENAME — when downloading files from the camera, specify the file name or file name pattern to use when storing the downloaded file on the local disk. when uploading a file to the camera, specify the filename to store the uploaded file as on the camera.

the --filename option accepts %a, %A, %b, %B, %d, %H, %k, %I, %l, %j, %m, %M, %S, %y, %%, (see date(1)) and, in addition, %n for the number, %C for the filename suffix, %f for the filename without suffix, %F for the foldername, %: for the complete filename in lowercase.

💀 note that %: is still in alpha stage, and the actual character or syntax may still be changed. e.g. it might be possible to use %#f and %#C for lower case versions, and %^f and %^C for upper case versions. it's giving "work in progress, don't come for her."

%n is the only conversion specifier to accept a padding character and width: %03n will pad with zeros to width 3 (e.g. print the number 7 as 007). leaving out the padding character (e.g. %3n) will use an implementation specific default padding character which may or may not be suitable for use in file names. so like, specify your padding. don't leave it on read. 🙈

the default value for this option can be specified in the ~/.gphoto/settings file as gphoto2=filename=value.

  • --filenumber FILENUMBER — if you specify the filename using the --filename option and use the %n pattern, this pattern usually starts at 1. for incremental usage, you can use --filenumber to have it start at another number FILENUMBER. glow-up for your numbering.
  • --usbid USBIDS — (expert only) override USB IDs. USBIDS must be of the form
DetectedVendorID:DetectedProductID=TreatAsVendorID:TreatAsProductID

to treat any USB device detected as DetectedVendorID:DetectedProductID as TreatAsVendorID:TreatAsProductID instead. all the VendorIDs and ProductIDs should be hexadecimal numbers beginning in C notation, i.e. beginning with '0x'.

example:

--usbid 0x4a9:0x306b=0x4a9:0x306c
🔥 "expert only" is not a vibe check, it's a warning label. proceed like the main character you are, but proceed knowing.
  • -a, --abilities — display the camera and driver abilities specified in the libgphoto2 driver. this all does not query the camera, it uses data provided by the library. use --summary to query an overview of the camera. so like, this one's reading from the library's notes, not asking the camera directly. iykyk.
  • -f, --folder FOLDER — specify camera folder (default="/").
  • -R, --recurse — recursion (default for download).
  • --no-recurse — no recursion (default for deletion).
  • -l, --list-folders — list folders in folder. folders in folders in folders. it's folders all the way down.
  • -L, --list-files — list files in folder.
  • -m, --mkdir NAME — create a directory.
  • -r, --rmdir NAME — remove a directory.
  • -n, --num-files — display number of files.
  • -p, --get-file RANGE — get files given in range.
  • -P, --get-all-files — get all files from folder.
  • -t, --get-thumbnail RANGE — get thumbnails given in range.
  • -T, --get-all-thumbnails — get all thumbnails from folder.
  • --get-raw-data RANGE — get raw data given in range.
  • --get-all-raw-data — get all raw data from folder.
  • --get-audio-data RANGE — get audio data given in range.
  • --get-all-audio-data — get all audio data from folder.
  • --get-exif RANGE — get Exif given in range.
  • --get-all-exif — get all Exif from folder.
  • --upload-metadata FILENAME — upload meta data for the specific file, taken from a file prefix with meta_. 🎀
  • --get-metadata RANGE — get meta data given in range.
  • --get-all-metadata — get all meta data from folder.
  • --force-overwrite — overwrite files without asking. no thoughts, just overwrite.
  • --skip-existing — skip files if they exist already on the local directory.
  • --new — only get not already downloaded files. this option depends on camera support of flagging already downloaded images and is not available for all drivers. so like, vibes vary by hardware, bestie.
  • -d, --delete-file RANGE — delete files given in range.
  • -D, --delete-all-files — delete all files in folder (defaults to --no-recurse).
  • -u, --upload-file FILENAME — upload a file to camera.
  • --capture-preview — capture a quick preview.
  • -B--bulb SECONDS — do a bulb capture for the specified amount of seconds.
  • --show-preview — capture a quick preview and displays it in the terminal using Ascii Art (if aalib was used during build). yes, Ascii Art. in the terminal. it's giving 1998 and honestly? iconic. ✨
  • -F COUNT, --frames COUNT — number of frames to capture in one run. default is infinite number of frames. literally infinite. go off.
  • -I SECONDS, --interval SECONDS — time between capture of multiple frames.

(since 2.4) if SIGUSR1 signal is received, a picture is taken immediately without waiting for the end of the current interval period (see the section called "SIGNALS"). a value of -1 will let gphoto2 wait forever, i.e. until a signal arrives. see also --reset-interval.

  • --reset-interval — setting this option will reset the time interval to the value given by the -I|--interval option when a SIGUSR1 signal is received in time-lapse mode.
  • --capture-image — snaps a pic and keeps it on the camera 💅 no download, the file just vibes on the card.
  • --capture-image-and-download — snaps a pic and immediately pulls it down to the computer, bestie. instantly. 🫶
  • --trigger-capture — triggers the capture and bounces right back out 🏃‍♀️✨ want the image actually downloaded too? that's a --wait-event-and-download situation.
heads up: this feature is only available for some camera brands and drivers 🙈
  • --reverse — when you're doing file operations like --get-all-files, -P or -T, this flips the order of the files being downloaded 🔄 iconic little reorder.
  • --keep — when doing --capture-image-and-download or interval capture, this keeps the images on the camera's memory card 💾 like, don't delete them, they live there.
  • --no-keep — when doing --capture-image-and-download or interval capture, this does not keep the images on the memory card after downloading them during capture. (this is the default ✨)
  • --keep-raw — when doing --capture-image-and-download or interval capture, this keeps the RAW images on the camera's memory card but still downloads the JPEGs 💅 lowkey perfect when you're doing dual mode capture and wanna review the JPEGs already during capture.
  • --capture-movie SECONDS — captures a movie 🎬 if the camera supports previews, it'll capture a stream of previews (motion-jpeg) as fast as the camera can go.

if no argument is specified, it captures preview frames until you press Ctrl+C. the arguments you can pass are either seconds of capture or a number of preview frames.

  • --capture-sound — captures an audio clip 🎙️ fr fr no driver supports this at this time 😭
  • --capture-tethered SECONDS, MILLISECONDS, COUNT or MATCHSTRING — lets gphoto2 wait for notifications from the camera that an object was added 🎀 this is the moment for tethered capture — you press the shutter on the camera and the image immediately transfers to the machine for processing. so slay.

pair it with --hook-script to immediately postprocess or display the images, and you've got a whole studio workflow going 👑

this option requires support in the driver and by the camera. currently newer Canon EOS and Nikon DLSR work.
  • --wait-event SECONDS, MILLISECONDS, COUNT or MATCHSTRING, --wait-event-and-download SECONDS, MILLISECONDS, COUNT or MATCHSTRING — lets gphoto2 wait for notifications from the camera for various events 👀 great for seeing what the camera does and waiting for objects to be added. the objects are kept on camera in the --wait-event version — with --wait-event-and-download they get downloaded. 🦋

--wait-event-and-download is equivalent to --capture-tethered.

the time to wait can be any of these, bestie:

  • full seconds with an s suffix
  • a number of milliseconds with an ms suffix
  • a number of events (just a number)
  • a sub-string to match

if nothing happens, a timeout is generated after 1 second, so a --wait-event=5 will take at most 5 seconds. a --wait-event=5s will take exactly 5 seconds ⏱️

it's also possible to wait for MATCHSTRING — for things like CAPTURECOMPLETE, FILEADDED, TIMEOUT or other events printed out 💫

if no argument is given, the wait time is 1 million events (basically forever 🌈).

in the download variant this can be used together with --hook-script to immediately postprocess or display the images — that can help a studio workflow 💖

this option requires support in the driver and by the camera.

if gphoto2 receives a SIGUSR1 during the wait, it'll immediately take a picture (similar to --capture-image) 📸 and depending on mode either leave it on camera or download it. (Since 2.5.28)

if gphoto2 receives a SIGUSR2 during the wait, it'll safely end the tethering. (Since 2.5.25)

  • --show-info RANGE — shows information for a single or multiple images 📊 like width, height, size and/or the capture time. the receipts, basically.
  • --config — starts a ncurses based text configuration menu 🖥️ note: gphoto2 needs to be built against CDK for this feature.
  • --list-config — lists all configuration entries 📝 every single one.
  • --list-all-config — lists all configuration entries and their values and choices 🎀 this is a combo of --list-config plus calling --get-config on all the entries.
  • --get-config CONFIGENTRY — gets the specified configuration entry 🔍 this lists the type, the current value, and also the available options of this configuration value.
  • --set-config CONFIGENTRY=CONFIGVALUE — sets the specified configuration entry 💅 for lists of choices of values, this setting first looks up CONFIGVALUE as a value and then as an index into the choice list. since that's not fully clear, you can use --set-config-index or --set-config-value to be more clear about what's being searched for.

look at the output of --get-config to see what values are possible to set here 👑

  • --set-config-index CONFIGENTRY=CONFIGINDEX — sets the specified configuration entry by specifying the index into the list of choices for the configuration value 🔢 obviously this only works for configuration settings that offer a list of choices.

peep the output of --get-config to see what indices are possible to set here.

  • --set-config-value CONFIGENTRY=CONFIGVALUE — sets the specified configuration entry by specifying its new value ✨ for lists of choices the value is looked up and set.

again, look at the output of --get-config to see what values are possible to set here 🫶

  • --reset — resets the specified (or autodetected) USB port 🔌 this resets the USB port of either the first auto-detected camera, or the port specified with --port usb:XXX,YYY. useful if somehow the protocol talking to the camera locked up — it simulates plugging out and in the camera 💀
  • --storage-info — displays information about the camera's storage media 💾 the tea on your card.
  • --summary — summary of camera status 📋
  • --manual — camera driver manual 📖
  • --about — about the camera driver 💁‍♀️
  • --shell — starts the gphoto2 shell, an interactive environment 🌸 see SHELL MODE for a detailed description.

🐚 SHELL MODE 🐚

okay so inside the shell, these are the commands you can use 👇

  • cd DIRECTORY — changes to the specified directory on the camera 📁
  • ls — lists the contents of the current directory on the camera 👀
  • lcd DIRECTORY — changes to the specified directory on the local machine 🏠
  • get FILENAME — downloads the specified file to the current directory ⬇️
  • put FILENAME — uploads the specified file from the current system directory to the camera's current directory ⬆️
  • get-thumbnail FILENAME — downloads the specified thumbnail to the current directory 🖼️
  • get-raw FILENAME — downloads the specified raw data to the current directory 🧚
  • get-exif FILENAME — downloads the specified Exif data to the current directory 📸
  • show-info FILENAME — shows information of the specified file 📊
  • delete FILENAME — deletes the specified file or directory 🗑️
  • mkdir DIRECTORY — creates a directory named DIRECTORY ✨
  • rmdir DIRECTORY — removes a directory named DIRECTORY 💅
  • show-exif FILENAME — shows EXIF information (only if compiled with EXIF support) 🔍
  • capture-image — captures a single image and keeps it on the camera 📷
  • capture-image-and-download — captures a single image and downloads it from the camera ⬇️📷
  • capture-preview — captures a preview image and downloads it from the camera 👁️
  • list-config — lists all configuration values 📝
  • get-config NAME — gets the configuration specified by NAME 🔧
  • set-config NAME=VALUE — sets the configuration specified by NAME to VALUE 🎀
  • set-config-value NAME=VALUE — sets the configuration specified by NAME to VALUE 💖
  • set-config-index NAME=VALUE — sets the configuration specified by NAME to the INDEX into the list of choices. works only for Menu or Radio button entries 🔘
  • wait-event COUNT or SECONDS — waits for events from the camera for the specified time in SECONDS (if suffixed with s) or the COUNT of events from the camera, where every second a timeout event happens ⏳ newly added images are kept on the camera.

default is 1 event 🦋

  • wait-event-and-download COUNT or SECONDS, capture-tethered COUNT or SECONDS — waits for events from the camera for the specified time in SECONDS (if suffixed with s) or the COUNT of events from the camera, where every second a timeout event happens ⏳ newly added images are downloaded from the camera.

default is 1 event 🫶

  • help, ? — displays command usage 🆘
  • exit, quit, q — exits the gphoto2 shell 👋

🌈 ENVIRONMENT VARIABLES 🌈

  • CAMLIBS — if set, defines the directory where the libgphoto2 library looks for its camera drivers (camlibs) 🎯 you only need to set this with non-standard installations.
  • IOLIBS — if set, defines the directory where the libgphoto2_port library looks for its I/O drivers (iolibs) 🔌 you only need to set this with non-standard installations.
  • LD_DEBUG — set this to all to receive lots of debug information regarding library loading on ld based systems 🧐 (yes, lots.)
  • USB_DEBUG — if set, defines the numeric debug level with which the libusb library will print messages 💬 in order to get some debug output, set it to 1.

⚡ SIGNALS ⚡

  • SIGUSR1 (since 2.4) — in time-lapse capture and in tethering or wait-event mode, receiving a SIGUSR1 signal makes gphoto2 take a picture immediately 📸

if the --reset-interval option is given, the time counter is reset to the value given by the -I|--interval option. note that the camera will need some time (from 50ms to a few seconds) to actually capture the image ⏱️

  • SIGUSR2 (since 2.5.26) — in tethering or wait-event mode, receiving a SIGUSR2 signal ends the tethering or wait-event mode 🛑 super useful if you don't know the end beforehand but still want to safely exit the waiting. iconic exit strategy, honestly.

🔗 SEE ALSO 🔗

  • libgphoto2(3)
  • The gPhoto2 Manual[1]
  • The gphoto.org website[2]
  • Digital Camera Support for UNIX, Linux and BSD[3]

🌸 EXAMPLES 🌸

okay bestie, these are the actual real-life things you're gonna type, and honestly? each one is a little slay 💅

  • gphoto2 --list-ports — shows you what kinds of ports you actually have — like USB and serial. that's it, that's the whole vibe. a little port inventory moment ✨
  • gphoto2 --auto-detect — shows what camera(s) you've got connected. the "who's in the group chat rn" of commands 🫶
  • gphoto2 --list-files — lists the files on your camera. your camera's camera roll, exposed.
  • gphoto2 --get-file 7-13 — grabs files number 7 through 13, using the list that gphoto2 --list-files gave you. so like, run --list-files first, find your faves, then pull that range. iykyk 🎀
  • gphoto2 --capture-image --interval 60 --hook-script /usr/share/doc/gphoto2/test-hook.sh — captures one (1) image every 60 seconds from now to eternity. no cap, eternity. and the example hook script gets called after each captured image has been stored on the computer, so it's lowkey doing the most for you 💖
gphoto2 --capture-image --interval 60 --hook-script /usr/share/doc/gphoto2/test-hook.sh

and if something's acting weird and you need to figure out why? to track down errors, you can add the --debug parameter to the gphoto2 command line — and if you're dealing with USB problems, set the environment variable USB_DEBUG=1. that's the detective arc, bestie 🔍

yeah the eternity one is real and it is not a drill — that command does not stop on its own. main character energy, but make it infinite 😭

👑 AUTHORS 👑

giving credit where credit is due, because these people built the thing we're all out here using 💜

  • Tim Waugh — Author.
  • Hans Ulrich Niedermann, current maintainer <gp@n-dimensional.de> — Author.
  • Michael J. Rensing — Author.
  • Marcus Meissner <marcus@jet.franken.de> — Author.
  • Miscellanous Contributors. — (yes, that's the spelling, i'm not touching it 🫶)
  • The gPhoto2 Team — Author.
  • Tim Waugh <twaugh@redhat.com> — Original man page author.
  • Hans Ulrich Niedermann <gp@n-dimensional.de> — Current man page editor.

🦋 NOTES 🦋

the receipts, the sources, the "go read this if you wanna know more" corner ✨

  1. The gPhoto2 Manual http://www.gphoto.org/doc/manual/
  2. The gphoto.org website http://www.gphoto.org/
  3. Digital Camera Support for UNIX, Linux and BSD http://www.teaser.fr/~hfiguiere/linux/digicam.html

and that's the whole page, bestie! 🎀 this little masterpiece comes from the source [FIXME: source] (yes, literally that, it's iconic in a cursed way 💀), with a pubdate of 2015-08-01, dated all the way back to August 2006, and it's GPHOTO2(1) — go forth and photograph things, you absolute legend 🌈👑💖

📦 where this page comes from