Welcome to xbox2local, a command line utility written in Python for downloading all your Xbox screenshots and game clips to your computer.
The goal of xbox2local is to make the process of saving your screenshots and game clips much faster. Each time you run it, it (1) detects all your media on the Xbox network that it hasn't saved before, (2) copies them to a local folder of your choosing, and (3) gives you the option of deleting them from the Xbox network to free up storage. I wrote this tool as an alternative to Team Xbox's ever changing capture policies and procedures so you can keep better control of your content.
As of the Xbox September 2023 Update, clips and screenshots are stored on the Xbox network for 90 days and otherwise you can back them up to OneDrive or external storage. On your Xbox, navigate to Captures > Manage > Select all > Upload to OneDrive or Copy to external storage. For many casual users, this functionality can (and should!) replace the functionality of the xbox2local script. For power users, xbox2local still offers the following benefits over the native Xbox functionality:
OneDrive/Pictures/Xbox Screenshots) and game clips (OneDrive/Videos/Xbox Game DVR).However, using xbox2local has the following drawbacks:
You'll need a command line (Unix-based, Windows Command Prompt, or macOS Terminal) and any Python installation version 3.6 or newer. You will also need the pandas, tqdm, and pathvalidate packages.
Have your Xbox Live (Microsoft) account email and password on hand. Both Free and Gold accounts are supported.
Navigate to OpenXBL, the API that xbox2local uses to interface with the Xbox network to download your media. Log in using your Microsoft account and verify your OpenXBL account via SMS.
On your OpenXBL profile page, scroll down to the box labeled "API KEYS" and press the "Create +" button. Copy the newly created API key (a string of letters, numbers, and hyphens) before navigating away from the page.
Clone this repository or download the latest release. Your directory structure will look like:
xbox2local
|--- users
| |--- example_user
| | |--- config.json
|--- ...
|--- xbox2local.pyRename the users/example_user directory to users/<your username>.
(If you need to download game media for multiple users, make multiple copies of this users/example_user directory.)
Update the contents of your config.json file with the following contents:
api_key field.media_dir field to the local directory to download screenshots and game clips to.gameclip_expiration_days field if desired.
This value controls the age of game clips that xbox2local will suggest deleting from the Xbox network to free up storage.
By default, this is set to 365 days.Run xbox2local with python xbox2local.py --username <your username>.
xbox2local provides the following command line arguments:
--username <USERNAME> allows you to specify an alternative user to load your config file (containing your OpenXBL API key and media directory), which is potentially useful if you have multiple accounts.After running xbox2local at least once in which it succeeds in downloading your media, a history.csv file will be created in your users/<your username> directory.
This file stores the metadata of every screenshot and game clip that xbox2local has previously downloaded so that, on subsequent runs, it does not download duplicates.
If for whatever reason you want to start fresh and redownload all media currently stored on the Xbox network, simply delete/move this file.
xbox2local does its best to notify you if anything goes wrong when communicating with the OpenXBL API or your Xbox account. Some common errors include:
This means that either you did not provide your OpenXBL API key in users/<your username>/config.json or the API key you provided is invalid.
This means that you have made more calls to OpenXBL API than your subscription plan allows. As of this writing, the free tier allows 150 requests per hour and there are larger quotas available via paid subscriptions. You can track your usage in real time on your OpenXBL profile page.
This should only occur if you're trying to delete a large number of game clips, and the error will naturally resolve by re-running the script after the per-hour request quota reset. See Issue #3 for further discussion.
This means that the media_dir path you provided in users/<your username>/config.json is not valid for your platform (Linux, Windows, or macOS).
The pathvalidate validate_filepath() function will print a more detailed error message.
Note: because sanitization rules differ slightly between platforms, running xbox2local with multiple command lines for the same media library may create different, similarly-named subfolders for the same game.
This message is expected behavior when there really isn't anything new to download. However, if you receive this message unexpectedly, check your Settings > Preferences > Capture & share > Automatically upload settings on your Xbox. This should be set to something other than Don't upload; otherwise, all screenshots and game clips you capture stay on your Xbox's local storage and are not uploaded to the Xbox network, so xbox2local cannot access them.
Updating an older version of xbox2local to a new release requires a basic understanding of semantic versioning, where version numbers are written as MAJOR.MINOR.PATCH.
If your older version and the updated version have the same MAJOR number, you can replace your xbox2local.py file with the newest version and things should just work.
Any backwards compatibility issues can be addressed by running the corresponding functions in update.py.
If you are updating to a new MAJOR version (e.g., from v1.#.# to v2.#.#), there may be additional changes you need to make manually.
The release notes for the corresponding major update (e.g., v2.0.0) will have instructions for those changes, if applicable.
If you'd like to leave feedback, feel free to open a new issue. If you'd like to contribute, please submit your code via a pull request.