Unsafe Code Guidelines, the Rust forum for what unsafe code means

What the repository is for

The stated purpose is to collect and discuss all sorts of questions that come up when writing unsafe code. That is a deliberately narrow description, and it is worth sitting with, because most people arriving at a repository named unsafe code guidelines expect a document telling them what to do.

What this is instead is a forum. The README says it is primarily used by the opsem team, the Rust team responsible for the operational semantics of the language, to track open questions around those semantics. Some questions that fall outside opsem's remit are also tracked when they are highly relevant to unsafe code authors, which puts them under the T-lang or T-type umbrellas.

That framing explains the whole structure. A repository of open questions is not a specification, and its value is different from a specification's value. When you read it, you learn two things: what the Rust language currently does not define clearly, and what the language team is actively trying to settle.

The second of those is the more valuable. If you are writing unsafe code and wondering whether a particular construct is sound, the fact that the question is on the list means the language does not currently give you a clear answer, and the discussion may contain the reasoning that will eventually become one.

The licensing is straightforward. All content is subject to the standard Rust licensing, with both LICENSE-MIT and LICENSE-APACHE in the repository. Interactions on the repository, whether on issues or pull requests or elsewhere, are governed by the Rust Code of Conduct.

The repository is not archived and the last push was on 2026-05-05, so it is still being worked on, though it is a slow-moving project by nature.

Where the answers actually live

The README is careful to point away from itself for authoritative answers, and following that pointer is the most useful thing a reader can do.

The current consensus is documented in the opsem FCPs, which live in the rust-lang/opsem-team repository, and in the Rust Language Reference. An FCP is a formal proposal process, and the ones collected here are the mechanism by which the language team turns a question into a decision.

The Unsafe Code Guidelines Reference, described in the README as a past effort to systematise a consensus on some of these questions, has mostly been archived. One part survives and is singled out as still useful: the glossary. If you are new to the topic, that page is the place to start, because it fixes the vocabulary. Terms like aliasing, provenance and validity have specific meanings in the Rust model, and the discussion threads are much harder to follow without them.

The Rustonomicon is the companion document. The README describes it as a draft document discussing unsafe code, intended to be brought into agreement with the content of this repository, and as an organised effort to explain how to write Rust code rather than a reference. The distinction between the two documents is worth holding on to: the guidelines repository is about what the language means, and the Nomicon is about how to use it.

So the reading path for a specific question is: the glossary for the vocabulary, this repository to find out whether the question is open and what the reasoning has been, the FCP list for the decision if one exists, and the Language Reference for the normative text. The Nomicon is what you read when you want to know how to write the code.

The repository layout and how the process is run

The top level of the repository shows how the work is organised, and it is the structure of a documentation project rather than a software one.

The reference/ directory holds the glossary and the reference pages that survived the archiving of the book effort. The active_discussion/ directory is where the open questions live, which is the part of the repository that changes as questions get answered and new ones arrive. wip/ is work in progress, and meeting-notes/ records what was discussed in the opsem meetings, which is a genuinely useful artefact because it shows the reasoning behind positions rather than just the outcome.

The resources/ directory holds supporting resources, and .github/ carries the issue and pull request templates that structure how contributions arrive.

The triagebot.toml at the root is the automation. It tells you that incoming issues are labelled and sorted automatically, which is what makes a repository with this volume of incoming questions manageable at all. Without an active triage process, an issue tracker like this either drowns or goes stale, and the configuration file is evidence that the project has invested in keeping it alive.

Two smaller signals are worth noting. The default branch is master rather than main, and the primary language is recorded as unknown, which is consistent with a repository whose content is prose rather than code.

There are no GitHub releases, which is appropriate: the output of this repository is not versioned artefacts but decisions, and those live in the FCPs and the Language Reference.

Working with the repository as a team

For a team that maintains unsafe Rust, this repository is most useful as a scheduled read and as a place to file questions, and both uses have a practical shape.

The scheduled read is short. The active discussion directory tells you which questions are currently open, and the meeting notes tell you what the team has been thinking about. A monthly skim of both is enough, and the value is in catching a question early: if you are about to write an unsafe abstraction around an unsettled area, finding that the language team is mid-decision on it changes what you should build.

Filing a question is the other use, and it is worth doing well. The triagebot configuration means incoming issues are labelled and routed automatically, so the description of the problem and the framing of the question do the work. A useful question states the construct you are unsure about, the program that would demonstrate the difference in behaviour, and what you currently assume. A question with a small reproducible example is one the opsem team can reason about, and the meeting notes show that the discussions that move forward are the ones with concrete cases attached.

There is a scope discipline to respect as well. The README says some questions outside opsem's remit are tracked when they are highly relevant to unsafe code authors, which means highly relevant, not merely related. A question about how to structure a crate of unsafe abstractions is not what this repository is for, and filing it there will not get it answered.

The final practical point is about the relationship between this repository and your own policies. Teams that write unsafe Rust usually need two separate documents: one stating what the language permits, which is where the Language Reference and the FCPs are authoritative, and one stating what the team permits, which is entirely your own decision. The Unsafe Code Guidelines repository informs the first and says nothing about the second, and confusing the two is how teams end up citing a discussion thread as though it were a rule.

What this means for someone writing unsafe Rust

The practical value of this repository shows up in two situations.

The first is when you are reviewing unsafe code and you want to know whether a construct is actually sound. Unsafe blocks in Rust are a promise the programmer makes to the compiler, and the soundness of that promise depends on rules that are subtle and sometimes not written down anywhere obvious. A question that appears in the active discussion list is a construct whose status is genuinely unsettled, which is exactly the information a reviewer wants.

The second is when you are trying to write something that the safe subset of the language cannot express. Knowing which questions are open tells you where the edges of the language are, and the meeting notes sometimes contain the reasoning that will shape the eventual answer.

What the repository is not is a checklist. It does not tell you which unsafe patterns are acceptable in practice, it does not rank constructs by risk, and it contains no rules that you should follow. The operational safety rules that most projects actually want are a different artefact, usually a lint configuration or an internal policy document.

There is also a scope point. This is about the semantics of unsafe Rust, not about other languages. The repository does not discuss how to write FFI bindings safely in the sense of validating pointers, and it does not cover the safe subset's own pitfalls. The vocabulary in the glossary is specific to Rust's model, and an expectation that it reads like a general systems programming manual will be disappointed.

For a team working in unsafe Rust, the useful pattern is to treat this repository as a periodic read rather than a reference to consult under pressure. The questions that remain open are the ones most likely to affect the code you are writing, and the FCP list tells you which of them the language team has already decided.

Editorial conclusion

Adopt this repository as a reference rather than as a dependency: it tells you which questions about unsafe Rust are still open and where the settled answers live. Do not treat it as normative guidance, because the README says the current consensus is documented in the opsem FCPs and the Rust Language Reference, not here. Verify first by reading the glossary if you are new to the topic, then check the FCP list for the specific question you have, since that is where the answers are actually recorded.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. rust-lang/unsafe-code-guidelines on GitHub