How to Install and Use Mojo on Ubuntu 26.04 and 24.04

Share

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:

Ubuntu terminal
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:

Ubuntu terminal
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:

Ubuntu terminal
lscpu | grep -i avx2

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:

Ubuntu terminal
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.

Ubuntu terminal
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:

Ubuntu terminal
sh "$pixi_installer"
Step 2: Reload Bash and verify Pixi

Reload the file updated by the installer, or open a new terminal:

Ubuntu 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:

Ubuntu terminal
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:

Ubuntu terminal
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:

Ubuntu terminal
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:

Ubuntu terminal
pixi run mojo main.mojo

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:

Ubuntu terminal
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:

Ubuntu terminal
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:

Ubuntu terminal
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:

Ubuntu terminal
pixi self-update

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:

Ubuntu terminal
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:

Ubuntu terminal
~/.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:

Ubuntu terminal
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:

Ubuntu terminal
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:

Ubuntu terminal
pixi clean

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:

Ubuntu terminal
pixi remove mojo

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:

Ubuntu terminal
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:

Ubuntu terminal
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

Continue learning

The official Mojo beginner tutorial develops a larger program. The Pixi documentation covers tasks, dependency constraints and environment management.

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