HORIBU1: Move upgrade instructions to their own page

2026-11-14T17:38:55Z

Move upgrade instructions to their own page

New page

{{3rd-party}}
{{Lich install nav}}
Use this page if Lich 5 is already installed and you want the newest version of Lich, Ruby or both. The current release is '''Lich {{Lich version}}''', which needs '''Ruby {{Lich version|ruby-series}}''' or newer.

New to Lich? Start with the [[Lich:Software/Installation|installation guides]] instead.


==Before you start==
# '''Check what you have.''' In the game, with Lich running, enter:
#* <code>;e echo LICH_VERSION</code> — your Lich version
#* <code>;e echo RUBY_VERSION</code> — your Ruby version
# '''Back up your Lich5 folder''', especially the <code>data</code> folder inside it, which holds your saved logins and settings.
# Pick the section that matches:
{| class="wikitable"
! You have !! Do this
|-
| Lich 5.7 or newer '''and''' Ruby {{Lich version|ruby-series}} or newer || [[#Update_Lich_only|Update Lich only]]
|-
| Ruby older than {{Lich version|ruby-series}} (any Lich 5) on Windows || [[#Windows:_update_Ruby_and_Lich_together|Windows: update Ruby and Lich together]]
|-
| Ruby older than {{Lich version|ruby-series}} on macOS or Linux || [[#macOS_and_Linux:_update_Ruby|macOS and Linux: update Ruby]], then [[#Update_Lich_only|update Lich]]
|-
| Lich 5.6 or older || Windows: [[#Windows:_update_Ruby_and_Lich_together|update Ruby and Lich together]]. macOS and Linux: [[#macOS_and_Linux:_update_Ruby|update Ruby]], then download Lich again as in your installation guide
|-
| Lich 4 || [[#Moving_from_Lich_4|Moving from Lich 4]]
|}

==Update Lich only==

For Lich 5.7 or newer, on any operating system. Lich 5.19 and newer needs Ruby {{Lich version|ruby-series}} or newer, so update Ruby first if yours is older.
# Back up your Lich5 folder.
# In the game, enter: <code>;lich5-update --update</code>
# Quit and restart Lich.

You are now running the latest version of Lich.

==Windows: update Ruby and Lich together==

This reinstalls both with the Ruby4Lich5 installer. It is for Windows only.
# Log out of all characters.
# Back up your Lich5 folder.
# Uninstall your existing Ruby4Lich5 from ''Settings → Apps'' (or ''Programs and Features''). Alternatively, rename the existing <code>C:\Ruby4Lich5</code> folder to <code>C:\Ruby4Lich5save</code>.
# Download the latest [https://github.com/elanthia-online/lich-5/releases/latest/download/Ruby4Lich5.exe Ruby4Lich5.exe installer].
# Run the installer with both '''Ruby''' and '''Lich 5''' selected.

You are now running the latest Lich and Ruby.

==Windows: update Ruby only==

Use this when Lich is already the latest version and only Ruby needs updating. If Lich is not already the latest version, use [[#Windows:_update_Ruby_and_Lich_together|update Ruby and Lich together]] instead.
# Log out of all characters.
# Back up your Lich5 folder.
# Uninstall your existing Ruby4Lich5 from ''Settings → Apps'' (or ''Programs and Features''), and check that <code>C:\Ruby4Lich5</code> is gone.
# Download the latest [https://github.com/elanthia-online/lich-5/releases/latest/download/Ruby4Lich5.exe Ruby4Lich5.exe installer].
# Run the installer and choose '''Ruby only'''.

You are now running the latest Ruby.

==macOS and Linux: update Ruby==
On macOS and Linux, Ruby is installed with rbenv, so you update it with rbenv. Gems belong to one Ruby version, so after installing a new Ruby you must run <code>bundle install</code> again.

'''1.''' Log out of all characters, and back up your Lich5 folder.

'''2.''' Update ruby-build so it knows about the newest Ruby versions:
* '''macOS''' (Homebrew): <code>brew upgrade rbenv ruby-build</code>
* '''Linux''': <code>git -C ~/.rbenv/plugins/ruby-build pull</code>

'''3.''' Install the new Ruby and make it the default:
{{#tag:pre|
rbenv install {{Lich version|ruby}}
rbenv global {{Lich version|ruby}}
ruby -v
}}
The last command should print a line that starts with <code>ruby {{Lich version|ruby}}</code>. If not, open a new terminal and try again.

'''4.''' Reinstall Lich's gems for the new Ruby. Use the block for your system; if you put Lich somewhere else, change the <code>cd</code> line to your Lich folder.

'''macOS''' (Lich on your Desktop, as in the [[Lich:Software/Installation/macOS|macOS guide]]):
<pre>
cd ~/Desktop/Lich5
bundle config set --local without 'development vscode'
bundle install
</pre>
'''Linux''' (Lich in your home folder, as in the [[Lich:Software/Installation/Linux|Linux guide]]):
<pre>
cd ~/Lich5
bundle config set --local without 'development vscode'
bundle install
</pre>

'''5.''' If Saga asks where Ruby is, give it the new path that <code>rbenv which ruby</code> prints.

Then [[#Update_Lich_only|update Lich]] if it is not already the latest version.

==Moving from Lich 4==

Lich 5 cannot use a Lich 4 installation, so there is no in-place upgrade. Back up your Lich 4 folder, uninstall any existing Ruby, then follow the [[Lich:Software/Installation|installation guide]] for your computer as a new install.

==Getting help==
Ask in the #scripting or #help channel of the [https://discord.gg/KF9Wr8u GemStone IV Discord].

{{Third-Party Software}}
[[Category:New Player]]

Lich:Software/Installation/Upgrading - Revision history

HORIBU1: Move upgrade instructions to their own page