{"id":14969642,"url":"https://github.com/owencochell/papermc-update","last_synced_at":"2025-10-26T09:30:51.172Z","repository":{"id":52307081,"uuid":"249809060","full_name":"OwenCochell/PaperMC-Update","owner":"OwenCochell","description":"A simple CLI python script that automates checking, downloading, and installing PaperMC server updates.","archived":false,"fork":false,"pushed_at":"2025-01-03T02:35:13.000Z","size":121,"stargazers_count":30,"open_issues_count":3,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T17:14:10.905Z","etag":null,"topics":["paperclip","papermc","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OwenCochell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-24T20:19:16.000Z","updated_at":"2025-01-03T09:22:50.000Z","dependencies_parsed_at":"2024-10-11T03:51:17.629Z","dependency_job_id":null,"html_url":"https://github.com/OwenCochell/PaperMC-Update","commit_stats":{"total_commits":48,"total_committers":4,"mean_commits":12.0,"dds":"0.22916666666666663","last_synced_commit":"6ff8a2f11f73b32c596c565ba1699ba198ed2d48"},"previous_names":["owencochell/papermc-update"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OwenCochell%2FPaperMC-Update","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OwenCochell%2FPaperMC-Update/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OwenCochell%2FPaperMC-Update/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OwenCochell%2FPaperMC-Update/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OwenCochell","download_url":"https://codeload.github.com/OwenCochell/PaperMC-Update/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238301178,"owners_count":19449396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["paperclip","papermc","python","python3"],"created_at":"2024-09-24T13:42:09.605Z","updated_at":"2025-10-26T09:30:51.165Z","avatar_url":"https://github.com/OwenCochell.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PaperMC-Update\n\nA simple CLI script that can check, download, and install PaperMC jar files.\n\nNOTE: This script can only be used for updating a [PaperMC Minecraft Server](https://papermc.io/). I highly recommend \ntheir implementation, as it is incredibly fast, supports multiple plugin formats, and is highly customizable. \nConsider switching if any of that sounds good to you. \nCheck out the [PaperMC Documentation](https://paper.readthedocs.io/en/latest/), \n[Download Page](https://papermc.io/downloads), and [GitHub](https://github.com/PaperMC).\n\n# Prerequisites\n\nYou must have Python 3.7+ installed. It should come pre-installed on most linux systems. \nThis script has no other dependencies, so all you need is python!\n\n## Windows\n\nWindows users can download python [here](https://www.python.org/downloads/windows/). The installation is very straightforward, \nalthough we recommend you add python to your PATH environment variable, as this makes using python much easier.\n\nMore information on installing/configuring python can be found [here](https://www.python.org/downloads/)\n(Any python 3.7+ version works, although I recommend the latest version).\n\nWe also supply windows binaries that can be ran directly on windows systems without python!\nWe use [PyInstaller](https://www.pyinstaller.org/) to build these binaries, and they are built using the one file option, or '-F'.\n\nThese binaries are much slower than running via python, and there might be some weird bugs or quirks.\nThey are built for windows only. We provide one with each version change.\n\nSometimes, these binaries are flagged as malicious programs(usually some form of trojan)\nbu numerous antivirus engines, sometimes including windows defender.\nThis is unfortunately quite common for freezed python binaries.\nThe best way to deal with the issue is to whitelist the executable in your antivirus. \n\nFind them [in the releases](https://github.com/Owen-Cochell/PaperMC-Update/releases)!\n\n## MacOS\n\nMacOS users can download python [here](https://www.python.org/downloads/mac-osx/).\n\nAgain, the installation is very straightforward, but more information can be found [here](https://docs.python.org/3/using/mac.html).\n\n## Linux\n\nPlease refer to your distribution's package manager for installing python.\n\n# Note on Python Versions:\n\nIn some systems, the 'python' command may point to an older version of python.\nAs stated above, we require python 3.7 or above, so it may be necessary to manually specify the python version to use.\n\nThis can be done like so:\n\n\u003epython[VERSION] script_to_run.py\n\nUsing this template, we can run python 3.9 like this:\n\n\u003epython3.9 script_to_run.py\n\nThis usage is most prevalent on linux devices,\nas they may have older versions of python installed for compatibility reasons.\n\nTo find the version of python your command points to, you can check it's version:\n\n\u003epython --version\n\nIf it is below 3.7, then you will have to manually specify the version to run!\n\nFrom this point on, we will use the default 'python' command in our examples,\nassuming that it's a valid python version.\nBe sure to specify your python version if necessary!\n\n# Usage\n\nYou may run the script like so:\n\n\u003e python server_update.py [PATH]\n\nWhere [PATH] is the path to your paperclip.jar file.\nBy default, when a new file is downloaded, \nit will be installed to this path under the same name.\n\nThis command will do the following:\n\n1. Attempt to load current paper version/build(`/PATH_TO_SERVER_JAR/version_history.json`, or elsewhere if specified. \nThis script only supports official builds of the paper server, meaning that we may fail to read config \ninformation for un-official builds). If no configuration data is found, and version info is not supplied via the \ncommand line, then the version and build for the currently installed server will default to 0.\n2. Check for a new version/build using the \n[PaperMC download API](https://docs.papermc.io/misc/downloads-api).\n3. If a new version/build is available, the default version and build(usually the latest) will be installed.\nIf you wish to select a version/build to install, then you can use '--version' and '--build' arguments to specify this. \nAlternatively, the user can be prompted to manually select which version/build they want to be installed. You can use \nthe `--interactive` flag for this.\n4. The selected version is downloaded to a temporary directory located somewhere on your computer\n(This directory is generated using the python tempfile module, meaning that it will be generated in a safe, \nunobtrusive manner, and will be automatically removed at termination of the script).\n\n    If the version selected has no available builds, then the script will print a warning and exit.\n5. The integrity of the file will be checked using the SHA256 hash provided by the PaperMC API.\nIf this check fails, the install will cancel.\n6. The currently installed version of the server is backed up to the temporary directory, and deleted.\nThis option can be disabled if you so choose.\n7. The newly downloaded server jar is moved from the temporary directory to the path of the old server, \nand will retain the name of the old server(If an error occurs for any reason during the instillation procedure, \nthen the script will attempt to recover your backed up version of the old server from the temporary directory).\n\nThis is the default operation of this script. However, you can fine tune the update process using the command line options\nlisted below.\n\n# Command Line Options:\n\nThe following command line options are available:\n\nSets the default value for the version to install, defaults to latest:\n\u003e-v [VERSION], --version [VERSION]\n\nSets the default value for the build to install, defaults to latest:\n\u003e-b [BUILD], --build [BUILD]\n\nSets the currently installed server version, ignores config data:\n\u003e-iv [VERSION]\n\nSets the currently installed server build, ignores config data:\n\u003e-ib [BUILD]\n\nSpecifies the output name of the new file:\n\u003e-o [NAME], --output [NAME]\n\nChecks for an update, does not install:\n\u003e-c, --check-only\n\nDoes not check for an update, skips to install:\n\u003e-nc, --no-check\n\nPrompts the user for the version they would like to install:\n\u003e-i, --interactive\n\nWill not load configuration data:\n\u003e-nlc, --no-load-config\n\nSets config file path(`/PATH_TO_SERVER_JAR/version_history.json` by default):\n\u003e-cf [CONFIG PATH], --config-file [CONFIG PATH]\n\nDisables the backup feature:\n\u003e-nb, --no-backup\n\nDisables the file integrity check:\n\u003e-ni, --no-integrity\n\nCopies the old jar file to a new location before deletion:\n\u003e-co, --copy-old\n\nInstalls a new paper jar to the specified location:\n\u003e-n, --new\n\nDisplays script version information:\n\u003e-V, --script-version\n\nDisplays server version, extracted from configuration file:\n\u003e-sv, --server-version\n\nWill only output errors and interactive questions to the terminal:\n\u003e-q, --quiet\n\nCopies the old file to a new location before the installation process:\n\u003e-co [PATH], --copy-old [PATH]\n\nDisplays stats on the selected version and build:\n\u003e-s, --stats\n\nSpecifies a custom user agent string, see below for why you should do this and what value you should choose:\n\u003e-ua [AGENT], --user-agent [AGENT]\n\nChecks GitHub for a new version of this script, and upgrades if necessary:\n\u003e-u, --upgrade\n\n## User Agent\n\nAccording to the new [API V3 documentation](https://docs.papermc.io/misc/downloads-api),\nit is **REQUIRED** to specify a custom user agent string.\nThis string must:\n\n- Clearly identify your software or company\n- Not be generic (defaults from curl, wget, ect.)\n- Includes a contact URL or email address (homepage, bot info page, support email, etc.)\n\nSome examples:\n\n```\nmc-image-helper/1.39.11 (https://github.com/itzg/docker-minecraft-server)\nnodecraft/packifier/1.0.0 (staff@nodecraft.com)\n```\n\nThese requirements were pulled directly from the documentation page linked above,\nbut they may change at any time. Please check the page regularly to ensure you are in compliance!\n\nYou may use the user agent option (`-ua [AGENT], --user-agent [AGENT]`) to specify this value.\nIt is optional, but **HIGHLY** recommended to set this value to something custom.\nIf a custom user agent is not provided, then this script will use the default value:\n\n```\nPaperMC-Update/VERSION (https://github.com/OwenCochell/PaperMC-Update)\n```\n\n(Where `VERSION` is the current version of this script)\n\nThis default value may be blocked at any time at the discretion of the PaperMC team!\nWhich means, if you do not specify a custom user agent, then this script may stop working!\nIn addition, this value will NOT change going forward (with the exception of the `VERSION` component).\nTo avoid any future problems, you should, again, use a custom user agent!\n\n## Special Keywords\n\nThe `-v`, `-b`, and interactive menu have special keywords\nthat can be used to do special things.\n\nThe `latest` keyword will automatically select the latest option available.\n\nThe `current` keyword will automatically select the currently installed value.\n\nFor example, lets say you have paper version 1.17 and build 60 installed.\nIf you want to get the latest build while maintaining your installed version,\nthen you can run server update like so:\n\n\u003epython server_update.py -v current [PATH]\n\nThis will only install new builds for your current version.\nYou can also use the `current` keyword to ensure that the version\nwill never change, regardless of what you have installed.\n\nThese keywords can be used in the interactive menu as well.\nYou can also use these keywords for selecting the build,\nalthough using the `current` keyword for build selection is not recommended! \n\n## Upgrading the Script\n\nThis script has the ability to upgrade itself!\nYou can do this by providing the `-u` parameter.\n\nWe do this by checking GitHub for any version changes.\nIf there is a change, then we download the new file\nand replace the currently running script with the new one.\nIf we are upgrading, then we will immediately exit after the operation,\nand no other actions will be done.\n\nPlease note, this upgrade operation is not compatible \nwith prebuilt binaries!\nIf you attempt to upgrade a pre-built binary,\nthen the script will print a warning and exit.\n\n## Deprecated Command Line Options\n\nThe following command line options are deprecated. They are still included for backwards compatibility,\nbut they do nothing and should not be used.\n\nDelete the config directory and all data within:\n\u003e-C, --cleanup\n\nWill not dump configuration data:\n\u003e-ndc, --no-dump-config\n\nSpecify which config directory should be used, defaults to `/DIR_OF_YOUR_SERVER_JAR_FILE/server_update`:\n\u003e--config [PATH]\n\nDoes not rename the new jar file:\n\u003e-nr, --no-rename\n\n# Note on filenames:\n\nWe have a couple ways of specifying the target and output filenames.\nIn these examples, 'old file' is the jar file that is currently installed.\n'New file' is the new file jar file that is being installed in its place.\n\nIn these coming examples, lets say you have a jar file you want to update located here:\n\u003eminecraft/paper.jar\n\n## The Best Way:\n\nThe easy way to tell the script where the file to update is located is to pass the path to said file, like so:\n\u003epython server_update.py minecraft/paper.jar\n\nIn this example, the old file will be backed up and deleted.\nWhen the new file is downloaded,\nit will be renamed to 'paper.jar' and moved to the directory the old file was in,\neffectively replacing it.\n\nThis is the recommended way to specify filenames!\nSpecifying the path to the jar file to update will allow the script to \nautomatically backup, move, and delete your files for you.\nIt also ensures that no matter the version or operations done to the target file,\nit will always have the same name.\n\n## Custom Output Names:\n\nYou can also specify a custom name of the new file like so:\n\u003epython server_update.py -o new_file.jar minecraft/paper.jar\n\nThis will do the same as the example above, \nbut instead of the new file retaining the old name,\nit will be renamed to the value you specified.\n\nIn our example, the old file will be backed up and deleted as usual,\nbut the new file will be renamed to 'new_file.jar',\nand moved to the directory the old file was in.\n\n## Keeping Old File:\n\nYou can use the '--copy-old' parameter\nto specify where you want the old file to be copied to.\n\nUsing the example from above:\n\u003epython server_update.py --copy-old paper_old.jar minecraft/paper.jar\n\nThe old file will still be deleted,\nbut a copy of it will be saved to 'paper_old.jar'.\n\nYou can also specify a path like this:\n\u003epython server_update.py --copy-old /new/path/file.jar minecraft/paper.jar\n\nIn this example, the old file is copied to '/new/path/file.jar'\nbefore the installation operation.\n\nThese options will be ignored if there is no target file!\n\nBe warned, that the old file will overwrite any files in the copy location\nthat share the same name!\n\n## Other Filename Stuff:\n\nIf no target filename is specified from the path,\nand no output filename is specified,\nthen the default filename will be used.\nThe default name usually looks something like this:\n\u003epaper-[VERSION]-[BUILD].jar\n\nSo, if you downloaded build 734 version 1.16.5:\n\u003epaper-1.16.5-734.jar\n\nYou can specify a directory to target instead of a file like this:\n\u003epython server_update.py minecraft/\n\nThis will automatically disable old file deletion and backup.\nThe newly downloaded file will simply be moved to the target directory,\nand will not be renamed(unless otherwise instructed by the '-o' parameter).\n\n# Examples:\n\nAutomatically check and download the latest version of the server:\n\u003epython server_update.py [PATH]\n\nDownload and install the latest build of version 1.13.2, without checking:\n\u003epython server_update.py --no-check --version 1.13.2 [PATH]\n\nInstall latest version, regardless of server version:\n\u003epython server_update.py --no-check [PATH]\n\nInstall specific version, regardless of installed version:\n\u003epython server_update.py --no-check --version [VERSION TO INSTALL] --build [BUILD TO INSTALL] [PATH]\n\nInteractively select a version you want to install, regardless of server version:\n\u003epython server_update.py --no-check --no-load --interactive [PATH]\n\nCheck to see if a newer version is available, does not install:\n\u003epython server_update.py --check-only [PATH]\n\nDisplay currently installed server version:\n\u003epython server_update.py --server-version [PATH]\n\nDisplay stats on version 1.16.5 build 432 before installation if update is available:\n\u003epython server_update.py --stats --version 1.16.5 --build 432 [PATH]\n\nDisplay stats on version 1.16.5 build 432 without installing anything:\n\u003epython server_update.py --stats --version 1.16.5, --build 432 -c -nc\n\nInstall a paper jar at the given location, without going through the update process.\nGreat if you want to set up a new server install.\n\u003epython server_update.py --new -o paper.jar [PATH]\n\nCopy the old file to a new location before the installation process:\n\u003epython server_update.py --copy-old /new/spot/old.jar [PATH]\n\nSelect the currently installed version as the version to install:\n\u003epython server_update.py -v current [PATH]\n\nUpgrades the script if necessary:\n\u003epython server_upgrade.py -u\n\n# Notes on Deprecated Features\n\nIn earlier versions of PaperMC-Update, the script would keep a config file in the users home directory\n(Or elsewhere if specified) containing version information on the server so it can be persistent across runs.\n\nThere were many problems with this: it created unnecessary files, it was inaccurate,\nand it made using PaperMC-Update a lot more complicated. Now, we read version info from a file named\n'version_history.json', which is kept in the root directory of the server, and is managed by the server itself. This\neliminates the need for 'script-generated configuration files',\nand makes PaperMC-Update easier to use and more accurate.\n\nHowever, there are some things to keep in mind:\n\n## Official Builds\n\nAs of now, PaperMC-Update only supports official builds of the server. As such, builds built locally or \nbuilds downloaded from unofficial sources may not be supported, \ndue to the fact that the config file format might be different, meaning that we can't pull version information from it.\n\nThis is something I would like to change at a later date if possible. If you have some insight into the format of \nthe config file across different builds, and have a way to identify and pull information from said file,\nthe please open a pull request. I would be happy to look it over! Be sure to include an example copy of the config \nfile.\n\nIf you are using this script and see any of the following messages:\n\n\u003eFailed to load config data - Not in JSON format!\n\n\u003eFailed to load config data - We want strings, not [DATATYPE_HERE]!\n\n\u003eUnable to load config data - Invalid Format, we support official builds only!\n\nThen please open an issue with the following information:\n\n1. Description of what you were trying to do\n2. All command arguments used\n3. Version/build you were trying to install\n4. Version/build of the currently installed server(If you know it)\n5. A copy of your 'version_history.json'\n\nI can use this information to not only fix the problems you are facing, but implement support \nfor your build. \n\n## Command Line Options\n\nThe old command line options were for managing the configuration file, such as removing it, creating it, and\ndumping information to it. These features are now obsolete, but the command line options are included for \nbackwards compatibility. These options do not appear on the help menu and they do nothing. This is to prevent usage errors. It is highly recommended that you stop using these options, and update any scripts or\nimplementations that use these features. These features might be removed in a later version if deemed necessary, so be warned.\n\n# Updater Class:\n\nDevelopers can import the Updater class into their own projects.\nThe updater class offers entry points into the PaperMC API,\nand allows users to get version/build data\nand download jar files.\n\nYou can import and create the class like so:\n\n```python\nfrom server_update import Update\n\nupdate = Update()\n```\n\nJust be sure the server_update.py file is present in the directory\nof the code importing it.\n\nYou should have a look at the docstrings in the source code for usage.\nAll arguments and outputs are described and typed,\nso implementing the Updater class into your code should be relatively painless.\n\n# Conclusion\n\nThis script provides a simple method to check/download/install PaperMC server updates. You can add your command to the \nbeginning of your start file, to ensure that you are always running the latest server version.\nIf you are hosting a server for a friend/customer, you can use this script to manage the update/install process for them, \nso they don't have to.\n\n# Changelog\n\nThe changelog has moved to CHANGELOG.md.\nAll current and future changes will be kept in that location.\n\n# Special Thanks\n\n[devStorm](https://github.com/developStorm) - Helped with configuration file management, and offered valuable insight\ninto the paper versioning file.\n\n# Pull Requests\n\nPull requests are welcome and encouraged!\n\nIf you have any bug fixes or changes, feel free to open a pull request.\nAny changes/fixes are greatly appreciated!\n\n# Issues/Bugs\n\nIf you have any questions on usage, or you have found a bug, please open a github issue. I would be happy to help!\n\nIf you are reporting a bug/error, be sure to include the following:\n\n1. Description of what you were doing\n2. All arguments used\n3. Version/build you are trying to install\n4. Version/build of the currently installed server(If you know it)\n5. Fail point(If provided, should be for most cases)\n6. Stack trace/error name(If provided, should be for most cases)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowencochell%2Fpapermc-update","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowencochell%2Fpapermc-update","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowencochell%2Fpapermc-update/lists"}