To install Mojo on Ubuntu 26.04 or 24.04, install Pixi, create a project using the stable Modular channel, then add the mojo package. Pixi keeps the compiler and its dependencies in a project environment.
Mojo is a programming language for writing compiled programs, including numerical and performance-focused code. This guide uses current Mojo 1.x syntax to run a first program and build an executable, then covers updates, Magic migration and cleanup. If a step fails, leave a comment with the error or contact us.
Before you begin
- Ubuntu 26.04 LTS or 24.04 LTS, internet access and a Bash terminal. Both releases meet the glibc 2.34+ baseline.
- 8 GiB RAM minimum. On x86_64, Mojo requires an x86-64-v3 CPU, including AVX2 and FMA. On ARM64, it requires Neoverse N1 or newer; an ARM64 label alone does not guarantee compatibility.
- A C compiler such as gcc or cc is required on Linux for linking. A GPU is optional for these CPU examples; GPU development needs additional packages and compatible hardware.
- Use sudo for Ubuntu packages only. Run Pixi and Mojo as your normal user. The shell steps below assume Ubuntu’s default Bash shell.
Install curl and the compiler tools:
sudo apt update && sudo apt install -y curl build-essential
See the official Mojo requirements for hardware and platform details.
1. Check Your CPU and Ubuntu Setup
Step 1: Check the release, architecture and linker
Run these before downloading the compiler:
cat /etc/os-release
uname -m
ldd --version | head -n 1
cc --version
free -h
Expect your Ubuntu release, x86_64 or aarch64, glibc 2.34 or newer, and a compiler version. The total memory should meet the 8 GiB requirement. If cc is missing, check that the prerequisite APT command finished successfully.
Step 2: Check AVX2 on x86_64
On an Intel or AMD machine, use this quick check:
A flags line containing avx2 is a useful first check, but it is not a complete x86-64-v3 certification. That baseline also requires AVX, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE and XSAVE. No output means AVX2 is not exposed to this Ubuntu system. Skip this check on ARM64; verify the actual processor model instead.
A virtual machine must expose the required CPU features to its guest. A supported host CPU is insufficient if the VM hides AVX2 or FMA. Upgrading Ubuntu cannot add instructions missing from an old physical CPU.
2. Install Pixi for Your User Account
Step 1: Install Pixi
The official installer downloads Pixi and adjusts your shell startup PATH. It executes a remote script, so use it only if you trust the Pixi project:
curl -fsSL https://pixi.sh/install.sh | sh
The default executable is ~/.pixi/bin/pixi. Do not prefix this command with sudo. If you prefer to read the script first, use the inspection alternative below instead of running both options.
pixi_installer=$(mktemp) && curl -fsSL https://pixi.sh/install.sh -o "$pixi_installer" && less "$pixi_installer"
Press q to leave less. After reviewing the script, run it in that same terminal if you accept its contents:
Step 2: Reload Bash and verify Pixi
Reload the file updated by the installer, or open a new terminal:
source ~/.bashrc
pixi --version
The version command should print a Pixi version. If you use Zsh or another shell, reload that shell’s startup file instead; do not source ~/.bashrc from Zsh. The Pixi installation guide explains the default paths and other shells.
3. Install Stable Mojo in a New Project
Step 1: Create the practice project
Start in your home directory. Use a new folder name if hello-mojo already exists:
cd ~
pixi init hello-mojo -c https://conda.modular.com/max/ -c conda-forge
This is the stable Modular channel documented in the current Mojo installation guide. The max segment is the channel name; it does not require installing the full MAX bundle. Do not substitute the Modular homepage or max-nightly.
Step 2: Add the standalone compiler
Continue only after project creation succeeds:
cd ~/hello-mojo
pixi add mojo
pixi run mojo --version
The final command should report a stable Mojo 1.x version. If it reports an older release or a development build, inspect the project channels and dependency constraints before using the examples below. Mojo is available inside this project through pixi run; a bare mojo command outside the environment may be unavailable.
Python users: an optional uv route
Python users can instead create a separate project with uv init hello-mojo-uv, enter it and use uv add mojo to install the Mojo wheels, then invoke the compiler with uv run mojo. Our uv installation and project guide for Ubuntu covers setting up uv; choose either uv or Pixi for the practice project so its environment remains easy to understand.
4. Write and Run Your First Mojo Program
Step 1: Create main.mojo
In ~/hello-mojo, create the following source file. This command overwrites main.mojo if it already exists, so keep a copy of any earlier work first:
cat > main.mojo <<'MOJO'
def main():
var message: String = "Hello from Mojo on Ubuntu!"
print(message)
MOJO
main is the program’s entry point. def defines a function, var declares a variable, String is its type, and print writes the message to the terminal. Use four spaces for the indented body.
Step 2: Run the source file
Run it inside the project environment:
You should see the following output:
Hello from Mojo on Ubuntu!
5. Use a Typed Function
Replace the greeting with a small calculation
This replaces the earlier main.mojo. It calculates the area of a rectangle with whole-number dimensions:
cat > main.mojo <<'MOJO'
def rectangle_area(width: Int, height: Int) -> Int:
return width * height
def main():
var width: Int = 6
var height: Int = 4
var area: Int = rectangle_area(width, height)
print("Area:", area)
MOJO
pixi run mojo main.mojo
The function accepts two Int arguments and returns an Int, as declared by -> Int. The three var declarations hold the inputs and result. Change width or height and rerun the command to calculate a different area.
Area: 24
These examples use Mojo 1.x def functions and var declarations. Older tutorials can use syntax that no longer matches the compiler. See the current function reference and variable reference when adapting older code.
6. Compile and Run an Executable
Build main.mojo
From ~/hello-mojo, compile the current rectangle example, then run the result only if compilation succeeds:
pixi run mojo build main.mojo && ./main
The compiler produces ./main by default; an existing file with that name can be replaced. The executable prints Area: 24. Running ./main is also the standalone command to use again after a successful build.
Editing main.mojo does not update the executable automatically. Build again after source changes. Keep the project environment available while developing, and test deployment separately on any target machine; this local example does not establish compatibility with every Linux system.
7. Understand Project Files and Update Mojo
Keep the manifest and lockfile
pixi.toml records channels, supported platforms and requested dependencies such as mojo.
pixi.lock records resolved versions, including dependencies of dependencies. Keep it with the project and do not edit it by hand.
.pixi/ contains the local project environments. It can be recreated from the project files.
For a shared project, commit the source, pixi.toml and pixi.lock to version control. Run pixi install in a fresh checkout to create its environment. A lockfile supports repeatability; it does not make unreviewed project tasks safe to execute.
Update the project compiler
From the project directory, update Mojo within the dependency range recorded in pixi.toml:
pixi update mojo
pixi run mojo --version
Review the manifest and lockfile changes, then rerun and rebuild your examples. If the configured range excludes a newer release, update will not silently cross it. Read the release notes before changing that range deliberately.
Update Pixi itself
For the official script installation used here, run:
This updates the Pixi program, rather than your project compiler. If you installed Pixi with another package manager, update it through that manager instead.
8. Migrate an Existing Magic Project
Skip this section for a new project. Back up or commit your existing project first, including its manifest and lockfile. The Magic-to-Pixi announcement explains the package-manager transition.
Rename the old manifest and use Pixi
Inside the backed-up Magic project, use this only when mojoproject.toml is your manifest and pixi.toml does not already exist:
mv -n mojoproject.toml pixi.toml
pixi install
pixi run mojo --version
The -n option avoids overwriting an existing pixi.toml. If both files exist, reconcile them manually before proceeding. Projects already using pyproject.toml do not need that rename; replace magic commands in scripts with their Pixi equivalents. Check channels and old compiler constraints separately: migrating the manager does not modernize source code or switch a nightly project to stable.
9. Fix Common Installation and Build Problems
Issue 1: pixi: command not found
Check the default binary directly:
~/.pixi/bin/pixi --version
If that works, reload ~/.bashrc in Bash and inspect its Pixi PATH entry. A temporary fix for the current shell is:
export PATH="$HOME/.pixi/bin:$PATH"
If the file is missing, review the installer error before trying again. Do not install a second copy with sudo to fix PATH.
Issue 2: Illegal instruction
On x86_64, rerun lscpu | grep -i avx2 and inspect the full CPU flags against x86-64-v3 requirements, including FMA. In a VM, check the guest CPU model and feature exposure. Changing VM CPU settings may require a shutdown; use a compatible host or provider if the hardware itself lacks the instructions. A container cannot supply missing physical CPU features.
Issue 3: A linker or cc is missing
Run cc --version. If no compiler is found, repeat the prerequisites command to install build-essential, confirm APT succeeds, then rerun the Mojo build. Do not treat a source-code error as a missing-linker error; read the complete message.
Issue 4: Mojo is missing or dependencies will not resolve
Return to the directory containing pixi.toml, then check:
pwd
cat pixi.toml
pixi list
Confirm the stable channel is https://conda.modular.com/max/ and that mojo is a dependency. Run pixi install for an existing manifest, or pixi add mojo if you have not added it yet. Check network errors and version constraints before deleting the lockfile. Do not disable TLS checks.
Issue 5: Code copied from an older tutorial fails
Check pixi run mojo --version and use the current def/var examples above. Preserve indentation and capitalization, including Int and String. Compile errors should identify a source line; resolve that error before trying to run a stale ./main executable.
Resume after a failed download
Fix the network or package-resolution error, return to the project directory and run pixi install again. Then check pixi run mojo --version and retry the example. Save your source and project files before cleaning an environment.
10. Clean Up or Uninstall
Option 1: Remove only the project environment
From the project directory, run:
This removes local environments, not main.mojo, pixi.toml or pixi.lock. The next pixi install or pixi run can recreate the environment and download packages again. It does not remove every shared Pixi cache or the Pixi program.
Option 2: Remove Mojo from this project
If you are keeping the project but no longer need its compiler dependency:
Pixi updates the manifest, lockfile and environment. This leaves source files and any ./main executable you built; remove generated output separately if you no longer need it.
Delete the practice folder only after backing it up
To remove the whole example, first confirm the exact folder and inspect its files:
cd ~
realpath -- "$HOME/hello-mojo"
ls -la -- "$HOME/hello-mojo"
If this is the practice project you intend to delete, move that folder to Trash using Files. This removes its source, lockfile, environment and executable together while providing a recovery route. Do not delete a shared repository or a different directory just because it has a similar name.
Remove the script-installed Pixi tool
Only do this when no other projects or global tools need Pixi. The default ~/.pixi directory may contain shared configuration, caches and global tool environments, so removing it affects more than hello-mojo. Check for custom PIXI_HOME locations before changing anything:
printf "%s\n" "${PIXI_HOME:-$HOME/.pixi}"
ls -ld -- "$HOME/.pixi"
grep -n -C 2 -F ".pixi" ~/.bashrc
Back up any settings you need. For the default installation, use Files to show hidden files and move only ~/.pixi to Trash. Open ~/.bashrc in a text editor and remove only the installer-added Pixi PATH line or block that refers to ~/.pixi/bin; preserve other PATH entries and unrelated shell settings. Other shells need the equivalent change in their own startup file. Open a fresh terminal and use command -v pixi to check whether another installation remains. Removing ~/.pixi does not remove project-local .pixi directories elsewhere.
Helpful Resources
Frequently Asked Questions
Can I use Mojo on Ubuntu 24.04 and 26.04?
Both releases meet the glibc 2.34+ baseline. You still need at least 8 GiB RAM, a supported CPU and a C compiler on Linux. These instructions use a user-owned Pixi environment.
Does Mojo need a GPU?
No GPU is needed for the CPU examples in this guide. GPU programming has additional hardware and software requirements and requires MAX.
Does AVX2 alone prove that my CPU supports Mojo?
No. AVX2 is one part of x86-64-v3, which also requires instructions including FMA, BMI1 and BMI2. A VM must expose the required features to Ubuntu. The x86 checks do not apply to ARM64.
Why does pixi run mojo work when mojo does not?
Pixi installs Mojo into a project environment. pixi run executes the compiler inside that environment without requiring you to activate a shell. Run it from the project directory.
Does pixi clean delete my source files?
pixi clean removes the local environments. It keeps your source, pixi.toml and pixi.lock so the environment can be recreated. Deleting the whole project folder also removes those files.
Can I install Mojo with uv instead?
Yes. In a separate uv project, use uv add mojo and invoke the compiler with uv run mojo. The CPU, memory and Linux linker requirements still apply.
More Ubuntu development guides: Manage development tools with mise · Set up Visual Studio Code
Views: 54