Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Officially supported platforms
Theos aims to be able to work on, and build for, the following platforms.
|Platform||Minimum OS version||Prerequisites||Targets supported|
|macOS||Mavericks (10.9)||Xcode 5.0 or newer. Xcode 4.4 supported, but only when building for ARMv6 (1st/2nd generation iPhone/iPod touch).||macOS, iOS, watchOS, tvOS1|
|iOS||5.0||Jailbroken device; CoolStar’s repository (and Sam Bingner’s repository if on iOS 11) installed; Theos Dependencies (package on BigBoss repo)||iOS|
|Linux||Linux kernel 3.16||build-essential (or equivalent for your distro), fakeroot, git, perl; CoolStar’s toolchain (direct ZIP download)||Linux, iOS|
|Windows Subsystem for Linux||Windows 10 build 14393||(Same as Linux)||(Same as Linux)|
|Windows: Cygwin2||Windows 7||curl, git, make, openssh, perl; CoolStar’s toolchain (tutorial)||Windows (Cygwin), iOS|
1 Supports jailbroken devices and simulators, where applicable.
2 Please consider using Windows Subsystem for Linux instead if possible. Cygwin works but is quite limited.
Other platforms (or versions older than listed above) may work, but be aware that they are unsupported. Theos may work on them now, but it may not in future. If you think we should officially support a platform not listed here, get in touch.
- Packages listed for your OS above
- Toolchain for the platform(s) you intend to build for
On macOS, Xcode is mandatory. The Command Line Tools package isn’t sufficient for Theos to work. Xcode includes toolchains for all Apple platforms. On any other platform, you will need to download the toolchain as linked above.
If you’re building for iOS, you should have:
- xz-utils (or lzma)
- An iOS SDK (this will be discussed in the next section)
On macOS, you can install like so (after installing Homebrew):
$ brew install ldid xz
On iOS, ldid is installed as part of the Theos Dependencies package. On Linux and Cygwin, ldid is included as part of the toolchain download.
Again — don’t forget the prerequisites listed in the table above!
⚠️ Warning if installing Theos on iOS: Unless you’re using the Electra jailbreak, the
gitcommand below currently won’t work due to a GitHub change that made it incompatible with Telesphoreo’s version of OpenSSL. saurik is working on an update. See issue #293 for more information and a workaround.
Decide where you want to install Theos. We recommend
~/theos or a similar directory that is in a location you can write to without having to use
You must set the
$THEOS variable in your environment, and export it so
make will see its value when you run it. Create or edit
~/.bash_profile (or equivalent for your shell of choice) and add this, replacing
~/theos with the full path to where Theos is installed if you chose another place:
For this change to take effect, you must restart your shell. The easiest way to do this is to simply open a new tab and close the previous one, or kill the app in the taskswitcher (iOS). Do
echo $THEOS on your shell to check if this is working.
~/.profile can be an alternative file used in place of
~/.bash_profile, so rename the file if the check above didn't work.
Then proceed to clone Theos to this directory:
$ git clone --recursive https://github.com/theos/theos.git $THEOS
Don’t forget the
--recursive flag. The Theos repository contains submodules, and this flag will clone them for you. If you forget this, you can fix it by running the updater:
Other common places are
/var/theos. If you want to use /var, /opt, or any other similar directory, keep in mind that they will not be writable except by root. You must use
sudo on the above command, and then change the owner to yourself:
$ sudo chown -R $(id -u):$(id -g) $THEOS
While it is possible to download Theos using the “Download ZIP” button on GitHub, this is discouraged as it will make it hard to update Theos in future.
In order to use
make troubleshoot, you need to install Ghostbin’s ghost.sh script.
$ curl https://ghostbin.com/ghost.sh -o $THEOS/bin/ghost $ chmod +x $THEOS/bin/ghost
If building for iOS, you will need an SDK. Xcode always provides the latest iOS SDK, but as of Xcode 7.3, it no longer includes private frameworks you can link against. This may be an issue when developing tweaks. You can get a patched SDK from our SDKs repo — click the “Download ZIP” button in the top-right, extract it, and copy the SDK(s) you want into the
sdks/ folder inside Theos.
If you are using Theos on Linux (or Cygwin or Windows Subsystem for Linux) you have to use an SDK for iOS 9.3 or below. the iOS 9.2 SDK is the version you should use on those platforms.
macOS and iOS should have been covered with the prerequisites. For Linux setups (WSL included) you'll have to do one more step:
$ mkdir -p $THEOS/toolchain $ unzip ios-toolchain_clang+llvm+ld64_latest_linux_x86_64.zip -d $THEOS/toolchain
Theos utilises a rolling release model, meaning the latest commit to the Git repo is the latest version of Theos available. Occasionally, you should update Theos. This can be done with:
If you get a “no such file or directory” error, you’re probably not using a recent version of Theos that added this script. As an alternative, switch to a directory containing a Theos makefile and then run:
$ make update-theos
(Both commands do the same thing.)
If you experience problems, updating Theos is the first thing you should do. This makes it a lot easier to track down the problem if you ask someone for help.
If you see the following when running the command:
make: *** No rule to make target 'update-theos'. Stop.
…then you’re using a legacy version of Theos. Read onto the next section.
Switching from DHowett’s or rpetrich’s Theos
Refer to Upgrading from legacy Theos.