derive.html


<!DOCTYPE HTML>
<html lang="en" >
    <head>
        <meta charset="UTF-8">
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <title>Using derive · Serde</title>
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="description" content="">
        <meta name="generator" content="GitBook 3.2.3">
        
        
    <link rel="stylesheet" href="gitbook/style.css">

    
                <link rel="stylesheet" href="gitbook/gitbook-plugin-codeblock-rust/block.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-checklist/checklist.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-anchors/plugin.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
                
            
        <link rel="stylesheet" href="styles/website.css">
        
    
    <meta name="HandheldFriendly" content="true"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black">
    <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
    <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">

    
    <link rel="next" href="attributes.html" />
    
    
    <link rel="prev" href="data-model.html" />
    

    </head>
    <body>
        
<div class="book with-summary font-size-2">
    <div class="book-summary">
        
            
                <nav role="navigation">
                

<ul class="summary">
    
    
        <li class="chapter " data-level="1.1" data-path="./">
            
                <a href="./">
            
                    
                    Overview
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.2" data-path="help.html">
            
                <a href="help.html">
            
                    
                    Help
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.3" data-path="data-model.html">
            
                <a href="data-model.html">
            
                    
                    Serde data model
            
                </a>
            

        </li>
    
        <li class="chapter active" data-level="1.4" data-path="derive.html">
            
                <a href="derive.html">
            
                    
                    Using derive
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5" data-path="attributes.html">
            
                <a href="attributes.html">
            
                    
                    Attributes
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.5.1" data-path="container-attrs.html">
            
                <a href="container-attrs.html">
            
                    
                    Container attributes
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5.2" data-path="variant-attrs.html">
            
                <a href="variant-attrs.html">
            
                    
                    Variant attributes
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5.3" data-path="field-attrs.html">
            
                <a href="field-attrs.html">
            
                    
                    Field attributes
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.6" data-path="custom-serialization.html">
            
                <a href="custom-serialization.html">
            
                    
                    Custom serialization
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.6.1" data-path="impl-serialize.html">
            
                <a href="impl-serialize.html">
            
                    
                    Implementing Serialize
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.2" data-path="impl-deserialize.html">
            
                <a href="impl-deserialize.html">
            
                    
                    Implementing Deserialize
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.3" data-path="unit-testing.html">
            
                <a href="unit-testing.html">
            
                    
                    Unit testing
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7" data-path="data-format.html">
            
                <a href="data-format.html">
            
                    
                    Writing a data format
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.1" data-path="conventions.html">
            
                <a href="conventions.html">
            
                    
                    Conventions
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.2" data-path="error-handling.html">
            
                <a href="error-handling.html">
            
                    
                    Error handling
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.3" data-path="impl-serializer.html">
            
                <a href="impl-serializer.html">
            
                    
                    Implementing a Serializer
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.4" data-path="impl-deserializer.html">
            
                <a href="impl-deserializer.html">
            
                    
                    Implementing a Deserializer
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.8" data-path="lifetimes.html">
            
                <a href="lifetimes.html">
            
                    
                    Deserializer lifetimes
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9" data-path="examples.html">
            
                <a href="examples.html">
            
                    
                    Examples
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.9.1" data-path="json.html">
            
                <a href="json.html">
            
                    
                    Structs and enums in JSON
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.2" data-path="enum-representations.html">
            
                <a href="enum-representations.html">
            
                    
                    Enum representations
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.3" data-path="attr-default.html">
            
                <a href="attr-default.html">
            
                    
                    Default value for a field
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.4" data-path="attr-flatten.html">
            
                <a href="attr-flatten.html">
            
                    
                    Struct flattening
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.5" data-path="attr-bound.html">
            
                <a href="attr-bound.html">
            
                    
                    Handwritten generic type bounds
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.6" data-path="deserialize-map.html">
            
                <a href="deserialize-map.html">
            
                    
                    Deserialize for custom map type
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.7" data-path="stream-array.html">
            
                <a href="stream-array.html">
            
                    
                    Array of values without buffering
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.8" data-path="enum-number.html">
            
                <a href="enum-number.html">
            
                    
                    Serialize enum as number
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.9" data-path="attr-rename.html">
            
                <a href="attr-rename.html">
            
                    
                    Serialize fields as camelCase
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.10" data-path="attr-skip-serializing.html">
            
                <a href="attr-skip-serializing.html">
            
                    
                    Skip serializing field
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.11" data-path="remote-derive.html">
            
                <a href="remote-derive.html">
            
                    
                    Derive for remote crate
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.12" data-path="deserialize-struct.html">
            
                <a href="deserialize-struct.html">
            
                    
                    Manually deserialize struct
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.13" data-path="ignored-any.html">
            
                <a href="ignored-any.html">
            
                    
                    Discarding data
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.14" data-path="transcode.html">
            
                <a href="transcode.html">
            
                    
                    Transcode into another format
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.15" data-path="string-or-struct.html">
            
                <a href="string-or-struct.html">
            
                    
                    Either string or struct
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.16" data-path="convert-error.html">
            
                <a href="convert-error.html">
            
                    
                    Convert error types
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.17" data-path="custom-date-format.html">
            
                <a href="custom-date-format.html">
            
                    
                    Custom date format
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.10" data-path="no-std.html">
            
                <a href="no-std.html">
            
                    
                    No-std support
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.11" data-path="feature-flags.html">
            
                <a href="feature-flags.html">
            
                    
                    Feature flags
            
                </a>
            

        </li>
    

</ul>


                </nav>
            
        
    </div>

    <div class="book-body">
        
            <div class="body-inner">
                
                    
<div class="book-header" role="navigation">
    

    <!-- Title -->
    <h1>
        <i class="fa fa-circle-o-notch fa-spin"></i>
        <a href="." >Using derive</a>
    </h1>
</div>


                    <div class="page-wrapper" tabindex="-1" role="main">
                        <div class="page-inner">
                            
                                <section class="normal markdown-section">
                                
                                <h1 id="using-derive"><a name="using-derive" class="plugin-anchor" href="#using-derive"><i class="fa fa-link" aria-hidden="true"></i></a>Using derive</h1>
<p>Serde provides a derive macro to generate implementations of the <code>Serialize</code> and
<code>Deserialize</code> traits for data structures defined in your crate, allowing them to
be represented conveniently in all of Serde&apos;s data formats.</p>
<p><strong>You only need to set this up if your code is using <code>#[derive(Serialize,
Deserialize)]</code>.</strong></p>
<p>This functionality is based on Rust&apos;s <code>#[derive]</code> mechanism, just like what you
would use to automatically derive implementations of the built-in <code>Clone</code>,
<code>Copy</code>, <code>Debug</code>, or other traits. It is able to generate implementations for
most structs and enums including ones with elaborate generic types or trait
bounds. On rare occasions, for an especially convoluted type you may need to
<a href="custom-serialization.html">implement the traits manually</a>.</p>
<p>These derives require a Rust compiler version 1.31 or newer.</p>
<ul class="checklist">
<li><label><div class="checkbox"><input type="checkbox"></div>Add <code>serde = { version = &quot;1.0&quot;, features = [&quot;derive&quot;] }</code> as a dependency in
Cargo.toml.</label></li>
<li><label><div class="checkbox"><input type="checkbox"></div>Ensure that all other Serde-based dependencies (for example serde_json) are on
a version that is compatible with serde 1.0.</label></li>
<li><label><div class="checkbox"><input type="checkbox"></div>On structs and enums that you want to serialize, import the derive macro as
<code>use serde::Serialize;</code> within the same module and write
<code>#[derive(Serialize)]</code> on the struct or enum.</label></li>
<li><label><div class="checkbox"><input type="checkbox"></div>Similarly import <code>use serde::Deserialize;</code> and write <code>#[derive(Deserialize)]</code>
on structs and enums that you want to deserialize.</label></li>
</ul>
<p>Here is the <code>Cargo.toml</code>:</p>
<div><p class="code-filename">Cargo.toml</p></div>
<pre><code class="lang-toml"><span class="hljs-section">[package]</span>
<span class="hljs-attr">name</span> = <span class="hljs-string">&quot;my-crate&quot;</span>
<span class="hljs-attr">version</span> = <span class="hljs-string">&quot;0.1.0&quot;</span>
<span class="hljs-attr">authors</span> = [<span class="hljs-string">&quot;Me &lt;user@rust-lang.org&gt;&quot;</span>]
<span class="hljs-section">
[dependencies]</span>
<span class="hljs-attr">serde</span> = { version = <span class="hljs-string">&quot;1.0&quot;</span>, features = [<span class="hljs-string">&quot;derive&quot;</span>] }

<span class="hljs-comment"># serde_json is just for the example, not required in general</span>
<span class="hljs-attr">serde_json</span> = <span class="hljs-string">&quot;1.0&quot;</span>
</code></pre>
<p>Now the <code>src/main.rs</code> which uses Serde&apos;s custom derives:</p>
<div><p class="code-filename">src/main.rs</p></div>
<pre><a class="playground-link" target="_blank" href="https://play.rust-lang.org/?edition=2018&amp;gist=1dbc76000e9875fac72c2865748842d7"></a><code class="lang-rust"><span class="hljs-keyword">use</span> serde::{Serialize, Deserialize};

<span class="hljs-meta">#[derive(Serialize, Deserialize, Debug)]</span>
<span class="hljs-class"><span class="hljs-keyword">struct</span> <span class="hljs-title">Point</span></span> {
    x: <span class="hljs-keyword">i32</span>,
    y: <span class="hljs-keyword">i32</span>,
}

<span class="hljs-function"><span class="hljs-keyword">fn</span> <span class="hljs-title">main</span></span>() {
    <span class="hljs-keyword">let</span> point = Point { x: <span class="hljs-number">1</span>, y: <span class="hljs-number">2</span> };

    <span class="hljs-keyword">let</span> serialized = serde_json::to_string(&amp;point).unwrap();
    <span class="hljs-built_in">println!</span>(<span class="hljs-string">&quot;serialized = {}&quot;</span>, serialized);

    <span class="hljs-keyword">let</span> deserialized: Point = serde_json::from_str(&amp;serialized).unwrap();
    <span class="hljs-built_in">println!</span>(<span class="hljs-string">&quot;deserialized = {:?}&quot;</span>, deserialized);
}
</code></pre>
<p>Here is the output:</p>
<pre><code>$ cargo run
serialized = {&quot;x&quot;:1,&quot;y&quot;:2}
deserialized = Point { x: 1, y: 2 }
</code></pre><h3 id="troubleshooting"><a name="troubleshooting" class="plugin-anchor" href="#troubleshooting"><i class="fa fa-link" aria-hidden="true"></i></a>Troubleshooting</h3>
<p>Sometimes you may see compile-time errors that tell you:</p>
<pre><code>the trait `serde::ser::Serialize` is not implemented for `...`
</code></pre><p>even though the struct or enum clearly has <code>#[derive(Serialize)]</code> on it.</p>
<p>This almost always means that you are using libraries that depend on
incompatible versions of Serde. You may be depending on serde 1.0 in your
Cargo.toml but using some other library that depends on serde 0.9. So the
<code>Serialize</code> trait from serde 1.0 may be implemented, but the library expects an
implementation of the <code>Serialize</code> trait from serde 0.9. From the Rust compiler&apos;s
perspective these are totally different traits.</p>
<p>The fix is to upgrade or downgrade libraries as appropriate until the Serde
versions match. The <code>cargo tree -d</code> command is helpful for finding all the
places that duplicate dependencies are being pulled in.</p>

                                
                                </section>
                            
                        </div>
                    </div>
                
            </div>

            
                <a href="data-model.html" class="navigation navigation-prev " aria-label="Previous page: Serde data model">
                    <i class="fa fa-angle-left"></i>
                </a>
                
                
                <a href="attributes.html" class="navigation navigation-next " aria-label="Next page: Attributes">
                    <i class="fa fa-angle-right"></i>
                </a>
                
            
    </div>

    <script>
        var gitbook = gitbook || [];
        gitbook.push(function() {
            gitbook.page.hasChanged({"page":{"title":"Using derive","level":"1.4","depth":1,"next":{"title":"Attributes","level":"1.5","depth":1,"path":"attributes.md","ref":"attributes.md","articles":[{"title":"Container attributes","level":"1.5.1","depth":2,"path":"container-attrs.md","ref":"container-attrs.md","articles":[]},{"title":"Variant attributes","level":"1.5.2","depth":2,"path":"variant-attrs.md","ref":"variant-attrs.md","articles":[]},{"title":"Field attributes","level":"1.5.3","depth":2,"path":"field-attrs.md","ref":"field-attrs.md","articles":[]}]},"previous":{"title":"Serde data model","level":"1.3","depth":1,"path":"data-model.md","ref":"data-model.md","articles":[]},"dir":"ltr"},"config":{"plugins":["-search","-sharing","sane-sidebar","codeblock-omit","codeblock-rust","edit-link","ga4","bulk-redirect","checklist","anchors"],"root":"_src","styles":{"pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css","website":"styles/website.css"},"pluginsConfig":{"checklist":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"codeblock-rust":{},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"sane-sidebar":{},"codeblock-omit":{},"bulk-redirect":{"redirectsFile":"redirects.json"},"ga4":{"anonymize_ip":true,"cookie_domain":"serde.rs","tag":"G-T5QD1R7FZW"},"edit-link":{"label":"Edit","base":"https://github.com/serde-rs/serde-rs.github.io/edit/master/_src"},"theme-default":{"styles":{"pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css","website":"styles/website.css"},"showLevel":false},"anchors":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Serde","language":"en","gitbook":"*"},"file":{"path":"derive.md","mtime":"2024-12-25T02:52:27.876Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2025-05-20T12:19:12.093Z"},"basePath":".","book":{"language":""}});
        });
    </script>
</div>

        
    <script src="gitbook/gitbook.js"></script>
    <script src="gitbook/theme.js"></script>
    
        
        <script src="gitbook/gitbook-plugin-sane-sidebar/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-edit-link/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-ga4/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
        
    
    </body>
</html>