C# File-Scoped Namespaces Explained
Learn how file-scoped namespaces in C# 10 reduce indentation and simplify source layout, and when to choose them over block-scoped namespaces.

File-scoped namespaces in C# 10 let you declare that all types in a file belong to a single namespace. Instead of wrapping every type in a block, you apply the namespace declaration to the entire file. This removes one indentation level from the file and makes the namespace association explicit.
The syntax is straightforward. A common layout places using directives first and then writes the namespace declaration with a semicolon:
using System;
namespace MyApplication.Services;
public class CustomerService
{
public Customer GetCustomer(int id)
{
// implementation
}
}This means CustomerService is a member of MyApplication.Services. There is no closing brace to manage, and the file's content is not indented inside a namespace block.
How File-Scoped Namespaces Differ from Block-Scoped Namespaces
Before C# 10, the only option was a block-scoped namespace, which wraps all types in braces:
namespace MyApplication.Services
{
public class CustomerService
{
public Customer GetCustomer(int id)
{
// implementation
}
}
}Both forms place CustomerService into the MyApplication.Services namespace. The difference is visual and structural. The block-scoped form adds an indentation level and requires a closing brace, which can make files with deeply nested types harder to scan. The file-scoped form keeps the code flush with the file's left margin, improving readability for larger files.
A file can contain at most one file-scoped namespace. If you need to declare types in different top-level namespaces in the same file, use block-scoped namespace declarations for each namespace, or split the types into separate files.
Why Use a File-Scoped Namespace?
The main motivation is to reduce nesting and improve code readability. By removing the indentation caused by a namespace block, you make the type structure more immediately visible. This is especially helpful in files that contain many types or long method definitions. It also makes the namespace association more obvious: when the namespace declaration sits near the top of the file, it reads like a file attribute rather than a wrapping construct.
Another benefit is consistency across a codebase. Many teams adopt file-scoped namespaces as their default style because it encourages a one-to-one mapping between files and types. When each file contains a single type, a file-scoped namespace creates a clean, predictable layout.
When to Prefer Block-Scoped Namespaces
Block-scoped namespaces remain useful when a file contains types in more than one top-level namespace. In that situation, a block-scoped declaration is required for each namespace. Often the cleaner answer is to split the types into separate files, but block-scoped namespaces are acceptable when the grouping is intentional.
Another common reason to stay with block-scoped namespaces is consistency with an existing older codebase. If a project already uses block-scoped style throughout, adopting file-scoped namespaces in only some files can create noisy diffs and inconsistent formatting.
Block-scoped declarations also support nested namespace declarations, such as:
namespace Root
{
namespace Nested
{
// types here
}
}This explicit nested block is available when you need it, although file-scoped style is often a simpler default for most files.
Compatibility and Compiler Requirements
File-scoped namespaces are a C# 10 feature, so they require a compiler that supports C# 10 or later. That generally means the .NET 6 SDK or a newer .NET SDK. You can use them in projects that target older frameworks, such as .NET Framework 4.8, as long as the compiler supports C# 10 and the project's language version is set to 10.0 or later. In a project file, you might set <LangVersion>10.0</LangVersion> when the SDK defaults to an older language version. The runtime does not need to provide any special support because namespaces are a compile-time construct.
When you compile a file with a file-scoped namespace, the generated IL is the same as it would be for the block-scoped version. There is no runtime performance difference. The choice is purely a source-code style and organization decision.
Formatting and Tooling Impact
EditorConfig and IDE formatting settings can enforce a preference. For example, you can set csharp_style_namespace_declarations to file_scoped or block_scoped according to your team's choice. The .NET SDK includes analyzers that can flag inconsistent namespace declarations. Many teams adopt file-scoped namespaces and then use dotnet format to keep the style consistent.
The main constraint is positional: a file-scoped namespace declaration must appear before any type declarations in the file. It is a top-level declaration, so it is not nested inside a type or another namespace. In practice, each file uses either one file-scoped namespace or one or more block-scoped namespaces.
Common Mistakes and How to Avoid Them
A frequent mistake is trying to declare two file-scoped namespaces in the same file. The following will not compile:
namespace A;
// types for A
namespace B;
// types for BThe compiler reports an error because a file can only have one file-scoped namespace. The fix is to use block-scoped namespaces for the additional namespace or to split the types into separate files.
Another mistake is placing a file-scoped namespace after a type declaration:
public class CustomerService
{
}
namespace MyApp.Services;This produces a compilation error because the namespace declaration must appear before all type declarations. The common file layout is using directives (if any), then the file-scoped namespace declaration, then types.
Also, be careful when refactoring existing code. Changing from block-scoped to file-scoped namespaces may cause a flood of indentation changes. While compilers handle it correctly, the diff can obscure the actual code changes. It is often safest to perform a mechanical conversion, perhaps with the IDE's quick action, and review the result carefully.
Choosing Between File-Scoped and Block-Scoped
Use file-scoped namespaces when you are starting a new project or when you want to modernize an existing codebase and can tolerate the large diff from adjusting indentation. They work best for files that contain a single type or a tight group of related types that share the same namespace. Choose block-scoped namespaces when you need multiple namespaces in one file, when you maintain legacy code that already uses block-scoped style, or when your team prefers the explicit block structure for historical reasons.
The decision has no impact on runtime behavior, so it comes down to readability, tooling support, and team consistency. File-scoped namespaces reduce nesting and make code easier to scan, and most teams that adopt the style find it a clear improvement in source-file organization.
Try matching browser tools
All toolsSmall utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related C# guides
All C# guidesC# Dispose vs Destructor: Key Differences Explained
c# dispose vs destructor: Understand the difference between Dispose and destructors in C#, when each runs, and how to manage unmanaged resources correctly.
C# Variable Declaration: Syntax and Practical Usage
Learn how to declare variables in C# with explicit types, var, and nullable annotations, and understand how defaults, scope, and readability affect your choices.
C# Primary Constructors for Classes: Syntax and Usage
Learn how to use C# primary constructors for classes: syntax, initialization, dependency injection, and limitations with practical examples.
C# IComparer: Custom Sorting with IComparer<T>
Learn how to implement IComparer<T> in C# to define custom sort order for arrays and lists, handle nulls, and avoid common performance pitfalls.
More in C#
All C# guidesThe guides filed next to this one in C#, in library order.