The scenario
You cloned a C# project from GitHub. The README states that .NET 8 is required. You open a terminal, type dnf install dotnet, and Fedora responds that the package is not found. You run dotnet --version and receive a command not found error. You need the toolchain to build the project, but the default repositories do not carry Microsoft's SDK. You will attach the official Microsoft repository, install the correct package, and verify the toolchain works before you commit to the project.
What is actually happening
.NET is a cross-platform framework. Microsoft maintains the upstream code and publishes official binaries for Linux distributions. Fedora does not package .NET in its default repositories because Microsoft controls the licensing and release schedule. Instead, Microsoft provides a preconfigured RPM repository that you attach to dnf. Once attached, dnf treats .NET packages exactly like any other Fedora package. It handles dependencies, tracks updates, and integrates with the system package database.
The SDK package contains everything needed to develop applications. It includes the Roslyn compiler, the CLI tools, the base class libraries, and the runtime. The runtime package contains only the execution environment. You install the SDK when you are writing code. You install the runtime when you are deploying an application to a server. The repository also carries ASP.NET Core hosting bundles, which include Kestrel and IIS integration modules.
Microsoft releases .NET on a fixed cadence. Long-term support versions receive three years of updates. Standard-term support versions receive eighteen months. Fedora releases a new version every six months. The N-2 release goes end-of-life when N+1 ships. You will need to upgrade your .NET version periodically to match Microsoft's support window. The dnf repository tracks these releases automatically. You do not need to manually swap repository URLs when Microsoft bumps a minor version.
Run dnf repoquery --list dotnet-sdk-8.0 to see exactly which files the package installs. Knowing the file layout prevents conflicts when you later install language extensions or IDE plugins.
The installation procedure
You will attach the Microsoft repository to your system, then install the SDK package. The repository URL changes with each Fedora release because the underlying glibc and dependency versions shift. Always match the repository to your current Fedora version.
Here is how to attach the repository for Fedora 40. Replace 40 with your version if you are running a different release.
sudo dnf install https://packages.microsoft.com/config/fedora/40/packages-microsoft-prod.rpm
# The RPM installs a repo file in /etc/yum.repos.d/
# It also imports the Microsoft GPG signing key into the dnf keyring
# dnf automatically registers the new repository for future transactions
Fedora keeps user configuration in /etc/ and ships package defaults in /usr/lib/. The repository file lands in /etc/yum.repos.d/, which means you can safely edit it if you need to change priority or disable it temporarily. Never modify files in /usr/lib/yum.repos.d/. Those files belong to the base system and will be overwritten on upgrade.
Here is how to install the .NET 8 SDK. The SDK package pulls in the runtime automatically, so you do not need to install both.
sudo dnf install dotnet-sdk-8.0
# The package name pins the major version to avoid accidental upgrades
# dnf resolves the runtime and ASP.NET Core dependencies automatically
# The installation places binaries in /usr/bin/ and libraries in /usr/lib64/dotnet/
Run dnf upgrade --refresh once a week to keep the Microsoft repository metadata current. The --refresh flag forces dnf to download fresh repository indexes instead of relying on cached timestamps. Microsoft updates the .NET repository frequently with security patches and minor version bumps. The --refresh flag prevents stale metadata from blocking legitimate updates.
Here is how to configure the CLI home directory if you want to isolate global tools from the system prefix.
export DOTNET_CLI_HOME="$HOME/.dotnet"
# Stores global tool installations in your home directory
# Prevents permission errors when running dotnet tool install
# Keeps system binaries clean and reproducible across machines
Add the export line to your ~/.bashrc or ~/.zshrc if you plan to use global CLI tools regularly. Global tools install into the path defined by DOTNET_CLI_HOME. Without it, dnf and manual installations compete for the same directories.
Verify the repository registration before proceeding. The Microsoft repo should appear in the enabled list with a valid GPG key.
sudo dnf repolist enabled
# Lists all active repositories and their metadata age
# Confirms packages-microsoft-prod is registered and reachable
# Shows the package count available for installation
Trust the package manager. Manual file edits drift, snapshots stay.
Verify the setup
The package manager reports success, but the toolchain needs a functional path and a working runtime. Check the version first.
dotnet --version
# Prints the exact SDK version, such as 8.0.401
# Confirms the binary is in your PATH and the runtime initializes correctly
# Fails immediately if the runtime libraries are missing or mismatched
Create a temporary test project to validate the compiler and runtime pipeline.
dotnet new console -o /tmp/dotnet-test
cd /tmp/dotnet-test
dotnet run
# Generates a minimal C# project structure
# Compiles the source code and executes the resulting binary
# Prints Hello World if the toolchain is fully operational
If the command prints the version and runs the test program without errors, the installation is complete. Clean up the test directory afterward.
Check the runtime environment variables to ensure the CLI knows where to find its libraries.
dotnet --info
# Displays the installed SDKs and runtimes
# Shows the base path for shared frameworks
# Reports any missing dependencies or architecture mismatches
Reboot before you debug. Half the time the symptom is gone.
Common pitfalls and error messages
The installation fails most often because of repository version mismatches or GPG key verification errors. Fedora enforces strict package signing. If the Microsoft key is missing or expired, dnf aborts the transaction.
You will see this error if the repository file points to the wrong Fedora release:
Error: Failed to download metadata for repo 'packages-microsoft-prod': Cannot prepare internal mirrorlist: No URLs in mirrorlist
The repository URL contains a hardcoded Fedora version number. If you upgraded from Fedora 39 to 40, the old repository file still points to fedora/39. Microsoft removes old release directories after a few months. Replace the repository file with the correct version for your current release.
You will see this error if the GPG key is not imported:
Error: GPG check FAILED
The packages-microsoft-prod.rpm package handles key import automatically. If you downloaded the repo file manually instead of installing the RPM, you must import the key yourself. Reinstall the RPM to fix the keyring.
You might encounter dependency conflicts if you previously installed .NET via a snap package or a manual tarball extraction. dnf will refuse to proceed and print a transaction test error. Remove the conflicting installation before proceeding.
sudo dnf remove dotnet-sdk-8.0 dotnet-runtime-8.0
# Clears manually installed binaries and leftover config files
# Allows dnf to take full ownership of the /usr/bin/dotnet symlink
# Prevents path collisions between package manager and manual installs
SELinux rarely blocks .NET execution, but it will log denials if you run the CLI from an unconfined directory with restrictive contexts. Check the audit log before disabling the policy.
sudo ausearch -m avc -ts recent
# Filters the audit log for Access Vector Cache denials
# Shows whether SELinux blocked dotnet or a dependent library
# Provides the exact source and target contexts for troubleshooting
Run journalctl -xe first. Read the actual error before guessing.
SDK versus runtime versus ASP.NET Core
The Microsoft repository carries three main package families. Choose the package that matches your workload.
Use dotnet-sdk-8.0 when you are developing applications, building libraries, or running tests on your workstation. The SDK contains the compiler, the CLI, and the runtime. It is heavy and unnecessary for production servers.
Use dotnet-runtime-8.0 when you are deploying a self-contained or framework-dependent application to a server. The runtime package contains only the execution environment and the base class libraries. It keeps the attack surface small and reduces disk usage.
Use aspnetcore-runtime-8.0 when you are hosting web applications that rely on Kestrel or IIS integration. This package includes the runtime plus the web server modules and HTTP.sys bindings. It does not include the compiler.
Use dotnet-apphost-pack-8.0 when you need to create self-contained deployments that bundle the runtime with your application. The pack provides the native host executables for different Linux architectures.
Stick to the SDK on development machines. Deploy only the runtime or ASP.NET Core runtime on servers. Mixing packages on the same system causes version skew and breaks the dotnet CLI.