How to Auto-Run Python Scripts at Startup in Agisoft Metashape

Automating your photogrammetry workflow can dramatically increase efficiency—especially in repetitive or enterprise tasks. Agisoft Metashape supports Python scripting, and you can even configure it to auto-run scripts at startup. This guide shows you how to set it up on Windows, macOS, and Linux, and includes best practices for script structure and debugging.

Why Auto-Run Python Scripts in Metashape?

Auto-running Python scripts allows you to:

• Automate routine workflows (e.g., import, align, build model, export)
• Enforce project standards across a team
• Trigger cloud uploads or database syncs on startup
• Batch-process image folders without user input

Where to Place Auto-Run Scripts

Metashape checks for a script file called startup.py in a specific user directory. If found, it will automatically execute this script on startup.

🟦 Windows

Place your script here:

%APPDATA%\Agisoft\Metashape Pro\scripts\startup.py

Example path: C:\Users\YourName\AppData\Roaming\Agisoft\Metashape Pro\scripts\startup.py

🍎 macOS

Use the following folder:

~/Library/Application Support/Agisoft/Metashape Pro/scripts/startup.py

🐧 Linux

For Linux systems:

~/.local/share/Agisoft/Metashape Pro/scripts/startup.py

Basic Structure of startup.py

import Metashape

def run_on_startup():
    doc = Metashape.app.document
    print("Metashape startup script running...")
    # Example task
    doc.addChunk()
    doc.chunk.label = "AutoCreatedChunk"
    print("Chunk created automatically.")

run_on_startup()

Common Use Cases

• Batch load images from a watched folder
• Start alignment when Metashape launches
• Connect to external database or fetch metadata
• Log project status or user activity

Example: Auto-Align Photos at Startup

import Metashape

def run_on_startup():
    chunk = Metashape.app.document.addChunk()
    chunk.addPhotos(["C:/images/image1.jpg", "C:/images/image2.jpg"])
    chunk.matchPhotos(accuracy=Metashape.HighAccuracy)
    chunk.alignCameras()
    print("Alignment complete.")

run_on_startup()

Advanced: Load from External Script

You can keep your core logic in another script and import it to keep startup.py clean:

import sys
sys.path.append("C:/MyScripts/")
import auto_processing
auto_processing.main()

How to Debug startup.py

• Use print() statements frequently
• Check the Metashape console for errors
• Run startup.py manually from the Python Console to test

Disabling or Temporarily Skipping Auto-Run

If your script causes issues, simply rename or delete startup.py. Alternatively, add a flag in the script to disable execution when needed:

if __name__ == "__main__":
    debug = True
    if not debug:
        run_on_startup()

Best Practices

• Keep startup.py lightweight—avoid heavy loops on launch
• Use logging instead of print for long-term scripts
• Validate file paths and inputs before execution
• Comment your code clearly for teammates

Conclusion

Auto-running Python scripts on Metashape startup is a powerful way to automate workflows, especially in production or multi-user environments. Whether you’re batch-processing data, setting up a standard project layout, or logging project activity, startup.py makes it easy to take control of your photogrammetry environment right from the moment the software opens.